<!DOCTYPE html>
<html lang="en">
<head>
<title>Shadow DOM</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<link rel="stylesheet" href="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/../../assets/styles/spec.css" type="text/css">
<link rel="stylesheet" href="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/../../assets/styles/prettify.css" type="text/css">
<link rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-ED" type="text/css" >
<script src="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/../../assets/scripts/bug-assist.js"></script>
<script src="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/../../assets/scripts/spec-assist.js"></script>
<script src="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/../../assets/scripts/prettify.js"></script>
<meta name="bug.blocked" content="14978">
<meta name="bug.short_desc" content="[Shadow]: ">
<meta name="bug.product" content="WebAppsWG">
<meta name="bug.component" content="Component Model">
</head>

<body>

<div class="head">

<div class="logo">
    <a target='_blank' href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a>
</div>

<h1>Shadow DOM</h1>
<h2 id="editors-draft">W3C Editor's Draft</h2>
<dl>
<dt>This version</dt>
    <dd><a target='_blank' href="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/index.html">http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/index.html</a></dd>
<dt>Latest working draft</dt>
    <dd><a target='_blank' href="http://www.w3.org/TR/shadow-dom/">http://www.w3.org/TR/shadow-dom/</a></dd>
<dt>Revision history</dt>
    <dd><a target='_blank' href="http://dvcs.w3.org/hg/webcomponents/log/tip/spec/shadow/index.html">http://dvcs.w3.org/hg/webcomponents/log/tip/spec/shadow/index.html</a></dd>
<dt>Participate</dt>
    <dd>Discuss on <a target='_blank' href="http://lists.w3.org/Archives/Public/public-webapps/">public-webapps@w3.org</a> (<a target='_blank' href="http://www.w3.org/2008/webapps/">Web Applications Working Group</a>)</dd>
    <dd><a target='_blank' href="https://www.w3.org/Bugs/Public/enter_bug.cgi?comment=&amp;blocked=14978&amp;short_desc=%5BShadow%5D%3A%20&amp;product=WebAppsWG&amp;component=Component%20Model">File bugs</a> (w3.org's <a target='_blank' href="https://www.w3.org/Bugs/Public/">Bugzilla</a>)</dd>
<dt>Editor</dt>
    <dd class="vcard"><span class="fn">Dimitri Glazkov</span>, <span class="org">Google</span>, &lt;<a class="email" href="mailto:dglazkov@chromium.org">dglazkov@chromium.org</a>&gt;</dd>
</dl>

<p class="copyright"><a target='_blank' href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> &copy; 2012 <a target='_blank' href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>&copy;</sup> (<a target='_blank' href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a target='_blank' href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a target='_blank' href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. <acronym title="World Wide Web Consortium">W3C</acronym> <a target='_blank' href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a target='_blank' href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a target='_blank' href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p>

<hr>

<h2 id="abstract">Abstract</h2>

<p>This specification describes a method of establishing and maintaining functional boundaries between DOM trees and how these trees interact with each other within a document, thus enabling better functional encapsulation within the DOM.</p>

<h2 id="status">Status of This Document</h2>

<p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current <abbr title="World Wide Web Consortium">W3C</abbr> publications and the latest revision of this technical report can be found in the <a target='_blank' href="http://www.w3.org/TR/"><abbr title="World Wide Web Consortium">W3C</abbr> technical reports index</a> at http://www.w3.org/TR/.</em></p>

<p>This document was published by the <a target='_blank' href="http://www.w3.org/2008/webapps/">Web Applications Working Group</a> as a First Public Working Draft. If you wish to make comments regarding this document, please send them to <a href="mailto:public-webapps@w3.org">public-webapps@w3.org</a> (<a href="mailto:public-webapps-request@w3.org?subject=subscribe">subscribe</a>, <a target='_blank' href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>). All feedback is welcome.</p><p>Publication as a Working Draft does not imply endorsement by the <abbr title="World Wide Web Consortium">W3C</abbr> Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.</p>

<p>This document was produced by a group operating under the <a target='_blank' href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>. <abbr title="World Wide Web Consortium">W3C</abbr> maintains a <a target='_blank' href="http://www.w3.org/2004/01/pp-impl/42538/status" rel="disclosure">public list of any patent disclosures</a> made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains <a target='_blank' href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a target='_blank' href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.</p>

</div>

<section class="toc">
<h2 id="toc">Table of Contents</h2>
<ol>
    <li><a href="#about"><span class="section">1</span> About this Document</a></li>
    <li><a href="#dependencies"><span class="section">2</span> Dependencies</a></li>
    <li><a href="#introduction"><span class="section">3</span> Introduction</a>
    <ol>
        <li><a href="#functional-encapsulation-example"><span class="section">3.1</span> Functional Encapsulation Example</a></li>
    </ol></li>
    <li><a href="#shadow-trees"><span class="section">4</span> Shadow Trees</a>
    <ol>
        <li><a href="#upper-boundary-encapsulation"><span class="section">4.1</span> Upper-boundary Encapsulation</a></li>
        <li><a href="#lower-boundary-encapsulation"><span class="section">4.2</span> Lower-boundary Encapsulation</a></li>
        <li><a href="#matching-insertion-points"><span class="section">4.3</span> Matching Insertion Points</a></li>
        <li><a href="#selecting-nodes-distributed-to-insertion-points"><span class="section">4.4</span> Matching Children, Distributed To Insertion Points</a></li>
        <li><a href="#multiple-shadow-trees"><span class="section">4.5</span> Hosting Multiple Shadow Trees</a></li>
        <li><a href="#reprojection"><span class="section">4.6</span> Reprojection</a></li>
        <li><a href="#composition"><span class="section">4.7</span> Composition</a></li>
        <li><a href="#nested-shadow-trees"><span class="section">4.8</span> Nested Shadow Trees</a></li>
        <li><a href="#rendering-shadow-trees"><span class="section">4.9</span> Rendering Shadow Trees</a></li>
        <li><a href="#custom-pseudo-elements"><span class="section">4.10</span> Custom Pseudo-elements</a></li>
    </ol></li>
    <li><a href="#events"><span class="section">5</span> Events</a>
    <ol>
        <li><a href="#event-retargeting"><span class="section">5.1</span> Event Retargeting</a></li>
        <li><a href="#retargeting-related-target"><span class="section">5.2</span> Retargeting <code>relatedTarget</code></a></li>
        <li><a href="#retargeting-focus-events"><span class="section">5.3</span> Retargeting Focus Events</a></li>
        <li><a href="#events-that-are-always-stopped"><span class="section">5.4</span> Events that are Always Stopped</a></li>
        <li><a href="#event-dispatch"><span class="section">5.5</span> Event Dispatch</a></li>
        <li><a href="#event-retargeting-example"><span class="section">5.6</span> Event Retargeting Example</a></li>
    </ol></li>
    <li><a href="#styles"><span class="section">6</span> Styles</a>
    <ol>
        <li><a href="#css-variables"><span class="section">6.1</span> CSS Variables</a></li>
        <li><a href="#text-decoration-property"><span class="section">6.2</span> <code>text-decoration</code> Property</a></li>
        <li><a href="#host-at-rule"><span class="section">6.3</span> <code>@host</code> @-rule</a></li>
    </ol></li>
    <li><a href="#user-interaction"><span class="section">7</span> User Interaction</a>
    <ol>
        <li><a href="#ranges-and-selection"><span class="section">7.1</span> Ranges and Selections</a></li>
        <li><a href="#focus-navigation"><span class="section">7.2</span> Focus Navigation</a></li>
        <li><a href="#active-element"><span class="section">7.3</span> Active Element</a></li>
        <li><a href="#editing"><span class="section">7.4</span> Editing</a></li>
        <li><a href="#assistive-technology"><span class="section">7.5</span> Assistive Technology</a></li>
    </ol>
    </li>
    <li><a href="#html-elements"><span class="section">8</span> HTML Elements in Shadow Trees</a>
    <ol>
        <li><a href="#inert-html-elements"><span class="section">8.1</span> Inert HTML Elements</a></li>
        <li><a href="#html-forms"><span class="section">8.2</span> HTML Forms</a></li>
    </ol></li>
    <li><a href="#html-elements-and-their-shadow-trees"><span class="section">9</span> HTML Elements and Their Shadow Trees</a>
    <li><a href="#elements-and-dom-objects"><span class="section">10</span> Elements and DOM Objects</a>
    <ol>
        <li><a href="#shadow-root-object"><span class="section">10.1</span> <code>ShadowRoot</code> Object</a>
        <ol>
            <li><a href="#shadow-root-attributes"><span class="section">10.1.1</span> <code>ShadowRoot</code> Attributes</a></li>
            <li><a href="#shadow-root-methods"><span class="section">10.1.2</span> <code>ShadowRoot</code> Methods</a></li>
        </ol></li>
        <li><a href="#extensions-to-element"><span class="section">10.2</span>  Extensions to <code>Element</code> Interface</a>
        <ol>
            <li><a href="#shadow-aware-attributes"><span class="section">10.2.1</span> <code>ShadowAware</code> Attributes</a></li>
            <li><a href="#shadow-aware-methods"><span class="section">10.2.2</span> <code>ShadowAware</code> Methods</a></li>
        </ol></li>
        <li><a href="#css-host-rule-interface"><span class="section">10.3</span> <code>CSSHostRule</code> Interface</a>
        <ol>
            <li><a href="#css-host-rule-attributes"><span class="section">10.3.1</span> <code>CSSHostRule</code> Attributes</a></li>
            <li><a href="#css-host-rule-methods"><span class="section">10.3.2</span> <code>CSSHostRule</code> Methods</a></li>
        </ol></li>
        <li><a href="#content-element"><span class="section">10.4</span> The <code>content</code> HTML element</a></li>
        <li><a href="#shadow-element"><span class="section">10.5</span> The <code>shadow</code> HTML element</a></li>
    </ol></li>
    <li><a href="#shadow-dom-example"><span class="section">11</span> Shadow DOM Example</a></li>
    <li><a href="#acknowledgements">Acknowledgements</a></li>
</ol>

</section>

<section class="math">

<h2 id="about">About this Document</h2>

<p>All diagrams, examples, notes, are non-normative, as well as sections explicitly marked as non-normative. Everything else in this specification is normative.</p>

<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in <a target='_blank' href="http://dev.w3.org/2006/xbl2/#refsRFC2119">RFC2119</a>. For readability, these words do not appear in all uppercase letters in this specification.</p>

<p>To help with layering and to avoid circular dependencies between various parts of specification, this document consists of three consecutive narratives:
<ol>
    <li>setting up the stage for the specification,</li>
    <li>explaining of the conceptual model and algorithms behind it, and</li>
    <li>expressing this model with DOM interfaces and HTML elements.</li>
</ol>
<p>In a sense, these parts can be viewed as <em>math</em>, which sets up the reasoning environment, <em>physics</em>, which is the theoretical reasoning about the concept, and <em>mechanics</em>, which is the practical application of this reasoning.</p>

<p>Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as <a target='_blank' href="http://en.wikipedia.org/wiki/Algorithm">algorithm</a>. The algorithms are defined in terms of processing equivalence. The <dfn id="dfn-processing-equivalence">processing equivalence</dfn> is a constraint imposed on the algorithm implementors, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.</p>

<h2 id="dependencies">Dependencies</h2>

<p>This document relies on the following specifications:</p>

<ul>
    <li><a target='_blank' href="http://www.w3.org/TR/CSS2/">CSS Level 2 Revision 1</a></li>
    <li><a target='_blank' href="http://www.w3.org/TR/cssom/">CSSOM</a></li>
    <li><a target='_blank' href="http://www.w3.org/TR/DOM-Level-3-Events/">DOM Level 3 Events</a></li>
    <li><a target='_blank' href="http://www.w3.org/TR/domcore/">DOM4 (DOM Core)</a></li>
    <li><a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">HTML</a></li>
    <li><a target='_blank' href="http://html5.org/specs/dom-parsing.html">DOM Parsing and Serialization</a></li>
    <li><a target='_blank' href="http://www.w3.org/TR/selectors/">Selectors Level 3</a></li>
    <li><a target='_blank' href="http://dev.w3.org/2006/webapi/selectors-api/">Selectors API Level 1</a></li>
</ul>

</section>

<section class="physics">

<h2 id="introduction">Introduction</h2>

<p>Web application developers often encounter the need to provide <a target='_blank' href="http://en.wikipedia.org/wiki/Encapsulation_(object-oriented_programming)">encapsulation</a> within a <a target='_blank' href="http://www.w3.org/TR/domcore/#introduction-to-the-dom">DOM</a> <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-tree">tree</a>. Despite being part of one <dfn id="dfn-document-tree">document tree</dfn> (a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-tree">tree</a> that has <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a> as its <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-tree-root">root</a>), there are typically many functional <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> fragments, as well as assumptions about these fragments operating independently. This specification calls this type of encapsulation a  <dfn id="dfn-functional-encapsulation">functional encapsulation</dfn>, as opposed to <dfn id="dfn-trust-encapsulation">trust encapsulation</dfn>, which deals with limiting information flow based on trust and ensuring security of data and state within an application.</p>

<p><a href="#dfn-functional-encapsulation">Functional encapsulation</a> is primarily concerned with establishing functional boundaries in a <a href="#dfn-document-tree">document tree</a>. A functional boundary (or just <dfn id="dfn-boundary">boundary</dfn> hereon) is a delineation of functional concerns between two loosely coupled units of functionality.</p>

<h3 id="functional-encapsulation-example">Functional Encapsulation Example</h3>

<p>A Web application user interface is commonly composed of several user interface elements (or <dfn id="dfn-widget">widgets</dfn>), each functionally its own tree. In cases where a widget is tasked with hosting other widgets, the need arises for the widget to understand where its <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> ends and another widget's <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> begins.</p>

<object data="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/../../assets/images/functional-encapsulation-example.svg" width="800" height="500"></object>

<p>This need for observing the functional <a href="#dfn-boundary">boundaries</a> in a <a href="#dfn-document-tree">document tree</a> is even larger when a <a href="#dfn-widget">widget</a> is operated on&mdash;added, moved, or removed in the <a href="#dfn-document-tree">document tree</a>&mdash;by an outside actor, such as the Web application that consumes these widgets. Unless the widget consumer knows exactly how a <a href="#dfn-widget">widget</a>'s <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> is designed, it is impossible for the consumer to reasonably operate on the widget. A typical workaround has been providing alternative means of operation by the widget developer, which, in striving for API consistency quickly extrapolates into a complete set of widget-specific, <a target='_blank' href="http://www.w3.org/TR/domcore/#introduction-to-the-dom">DOM</a>-like APIs.</p>

<h2 id="shadow-trees">Shadow Trees</h2>

<p>To solve this problem at its core, a new abstraction is introduced. The <dfn id="dfn-shadow-dom">shadow DOM</dfn> allows multiple <a target='_blank' href="http://www.w3.org/TR/domcore/#introduction-to-the-dom">DOM</a> trees (in addition to the <a href="#dfn-document-tree">document tree</a>) to be composed into one larger <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> when rendered. The existence of multiple <a target='_blank' href="http://www.w3.org/TR/domcore/#introduction-to-the-dom">DOM</a> trees is enabled by letting any <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> in the <a href="#dfn-document-tree">document tree</a> to host one or more additional <a target='_blank' href="http://www.w3.org/TR/domcore/#introduction-to-the-dom">DOM</a> trees. These <dfn id="dfn-shadow-tree">shadow trees</dfn> are governed by a set of rules that establish encapsulation <a href="#dfn-boundary">boundaries</a> while retaining the standard <a target='_blank' href="http://www.w3.org/TR/domcore/#introduction-to-the-dom">DOM</a> composability semantics.</p>

<p>The encapsulation <a href="#dfn-boundary">boundaries</a> between the <a href="dfn-document-tree">document tree</a> and <a href="#dfn-shadow-tree">shadow trees</a> are called <dfn id="dfn-shadow-boundary">shadow boundaries</dfn>. The <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a> that host <a href="#dfn-shadow-tree">shadow trees</a> are called <dfn id="dfn-shadow-host">shadow hosts</dfn>, and the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-tree-root">roots</a> of the <a href="#dfn-shadow-tree">shadow trees</a> are called <dfn id="dfn-shadow-root">shadow roots</dfn>.</p>

<object data="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/../../assets/images/shadow-trees.svg" width="800" height="430"></object>

<p>When rendered, the <a href="#dfn-shadow-tree">shadow tree</a> takes place of the <a href="#dfn-shadow-host">shadow host</a>'s content.</p>

<object data="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/../../assets/images/shadow-rendering.svg" width="450" height="400"></object>

<p>To enable composition of <a href="#dfn-shadow-host">shadow host</a>'s children and the <a href="#dfn-shadow-tree">shadow tree</a>, a notion of insertion points is added to the abstraction. An <dfn id="dfn-insertion-point">insertion point</dfn> is a defined location in the <a href="#dfn-shadow-tree">shadow tree</a>, to which the <a href="#dfn-shadow-host">shadow host</a>'s children are transposed when rendering. The mechanism that determines which <a href="#dfn-shadow-host">shadow host</a>'s children are transposed into which <a href="#dfn-insertion-point">insertion points</a> is called <dfn id="dfn-distribution">distribution</dfn>.</p>

<object data="http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow/../../assets/images/insertion-points.svg" width="800" height="900"></object>

<p>Thus, the encapsulation of a <a href="#dfn-shadow-tree">shadow tree</a> can be viewed as a two-fold problem:
<ol>
    <li>the <dfn id="dfn-upper-boundary-encapsulation">upper-boundary encapsulation</dfn>, or governing the boundary between the shadow root and the shadow host; and</li>
    <li>the <dfn id="dfn-lower-boundary-encapsulation">lower-boundary encapsulation</dfn>, or governing the boundary between the insertion points and the shadow host's children.</li>
</ol>

<h3 id="upper-boundary-encapsulation">Upper-boundary Encapsulation</h3>

<p>To maintain the upper-boundary encapsulation, the following <dfn id="dfn-scoping-constraints">scoping constraints</dfn> <strong>must</strong> apply to all <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> in a <a href="#dfn-shadow-tree">shadow tree</a>:</p>
<ul>
    <li>The <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-node-ownerdocument"><code>ownerDocument</code></a> property refers to the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a> of the <a href="#dfn-shadow-host">shadow host</a></li>
    <li>The <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> and <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-document-nameditem-filter">named elements</a> <strong>are not</strong> accessible using <a href="#dfn-shadow-host">shadow host</a>'s <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a> <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-tree-accessors">DOM tree accessors</a> or with <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window">Window</a> object <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#named-access-on-the-window-object">named properties</a></li>
    <li>The <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> <strong>are not</strong> present in any of the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a>'s <a target='_blank' href="http://www.w3.org/TR/dom/#interface-nodelist"><code>NodeList</code></a>, <a target='_blank' href="http://www.w3.org/TR/dom/#interface-htmlcollection"><code>HTMLCollection</code></a>, or <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#domelementmap-0"><code>DOMElementMap</code></a> instances</li>
    <li>The <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> with a unique <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-id">id</a> and <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-document-nameditem-filter">named elements</a> <strong>are not</strong> addressable from any attributes of <a target='_blank' href="http://www.w3.org/TR/domcore/#element">elements</a> in <a href="#dfn-shadow-host">shadow host</a>'s <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a></li>
    <li>The style sheets, represented by the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> <strong>are not</strong> accessible using <a href="#dfn-shadow-host">shadow host</a> <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a>'s <a target='_blank' href="http://www.w3.org/TR/cssom/#extensions-to-the-document-interface">CSSOM extensions</a></li>
    <li>The <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> <strong>are</strong> accessible using <a href="#dfn-shadow-root">shadow root</a>'s <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-tree-accessors">DOM tree accessor</a> methods</li>
    <li>The <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> with a unique <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-id">id</a> and <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-document-nameditem-filter">named elements</a> <strong>are</strong> addressable from any attributes of <a target='_blank' href="http://www.w3.org/TR/domcore/#element">elements</a> in the same <a href="#dfn-shadow-tree">shadow tree</a></li>
    <li>The <a target='_blank' href="http://www.w3.org/TR/selectors/">selectors</a> <strong>must not</strong> cross the <a href="#dfn-shadow-boundary">shadow boundary</a> from the <a href="#dfn-document-tree">document tree</a> into the <a href="#dfn-shadow-tree">shadow tree</a></li>
</ul>
<p>For convenience, the <a href="#dfn-shadow-root">shadow root</a> provides its own set of <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-tree-accessors">DOM tree accessor</a> methods. No <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> other than <a href="#dfn-shadow-root">shadow root</a> descendants are accessible with these methods.</p>

<p>The <a target='_blank' href="http://www.w3.org/TR/dom/#dom-node-parentnode"><code>parentNode</code></a> and <a target='_blank' href="http://www.w3.org/TR/dom/#dom-node-parentelement"><code>parentElement</code></a> attributes of the <a href="#dfn-shadow-root">shadow root</a> object <strong>must</strong> always return <code>null</code>.</p>

<h3 id="lower-boundary-encapsulation">Lower-boundary Encapsulation</h3>

<p>To maintain the lower-boundary encapsulation, the <a href="#dfn-distribution">distribution</a> of child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> of the <a href="#dfn-shadow-host">shadow host</a> among the <a href="#dfn-insertion-point">insertion points</a> in the associated <a href="#dfn-shadow-tree">shadow tree</a> <strong>must</strong> have the following traits:</p>
<ul>
    <li>The <a href="#dfn-distribution">distribution</a> does not affect the state of the <a href="#dfn-document-tree">document tree</a> or <a href="#dfn-shadow-tree">shadow trees</a></li>
    <li>Each insertion point participates in <a href="#dfn-distribution">distribution</a> by providing a matching criteria for the child nodes. The <dfn id="dfn-matching-criteria">matching criteria</dfn> determines whether a given  <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> could be <a href="#dfn-distribution">distributed</a> to a given insertion point</li>
    <li>The <a href="#dfn-distribution">distribution</a> is a result of executing a stable algorithm</li>
    <li>The <a href="#dfn-distribution">distribution</a> itself does not change the variables affecting the <a href="#dfn-distribution">distribution</a></li>
    <li>The <a href="#dfn-distribution">distribution</a> reoccurs whenever any variable affecting it is changed</li>
</ul>

<p>An <a href="#dfn-insertion-point">insertion point</a> may be <strong>active</strong> or <strong>inactive</strong>. An <dfn id="dfn-active-insertion-point">active</dfn> insertion point participates in the <a href="#dfn-distribution">distribution</a> process, whereas the <dfn id="dfn-inactive-insertion-point">inactive</dfn> insertion does not. If not specifically set to be inactive, the insertion point <strong>must</strong> be considered <strong>active</strong>.</p>

<p>If an <a href="#dfn-insertion-point">insertion point</a> is not in a <a href="#dfn-shadow-tree">shadow tree</a>, it <strong>must</strong> have the same rendering behavior as the <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/#htmlunknownelement"><code>HTMLUnknownElement</code></a>.</p>

<p>The <dfn id="dfn-distribution-algorithm">distribution algorithm</dfn> <strong>must</strong> produce an outcome that is <a href="#dfn-processing-equivalence">equivalent</a> of the outcome of processing these steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>TREE</var>, a <a href="#dfn-shadow-tree">shadow tree</a></dd>
    <dd><var>POOL</var>, a list of <a target='_blank' href="http://www.w3.org/TR/domcore/#introduction-to-the-dom">DOM</a> nodes</dd>
<dt>Output</dt>
    <dd>The <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> in <var>POOL</var> are <a href="#dfn-distribution">distributed</a> among <a href="#dfn-insertion-point">insertion points</a> in <var>TREE</var>.</dd>
</dl>

<ol>
    <li><dfn id="algo-distribution-repeat-outer">Repeat</dfn> for each <a href="#dfn-active-insertion-point">active</a> <a href="#dfn-insertion-point">insertion point</a> in <var>TREE</var>, in <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#tree-order">tree order</a>:
    <ol>
        <li>Let <var>POINT</var> be the current insertion point</li>
        <li><dfn id="algo-distribution-repeat">Repeat</dfn> for each <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> in <var>POOL</var>:
        <ol>
            <li>Let <var>NODE</var> be the current <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a></li>
            <li>If the <var>NODE</var> matches <var>POINT</var>'s <a href="#dfn-matching-criteria">matching criteria</a>:
                <ol>
                    <li><a href="#dfn-distribution">Distribute</a> the <var>NODE</var> to <var>POINT</var></li>
                    <li>Remove <var>NODE</var> from the <var>POOL</var></li>
                </ol></li>
            <li>Otherwise, continue to <a href="#algo-distribution-repeat">repeat</a></li>
        </ol></li>
        <li>Continue to <a href="#algo-distribution-repeat-outer">repeat</a></li>
    </ol></li>
</ol>
</div>

<h3 id="matching-insertion-points">Matching Insertion Points</h3>

<p>The <a href="#dfn-matching-criteria">matching criteria</a> for <a href="#dfn-insertion-point">insertion point</a> is defined as a set of selector fragments. Each <dfn id="dfn-selector-fragment">selector fragment</dfn> is a fragment in a fictional <a target='_blank' href="http://www.w3.org/TR/css3-selectors">selector</a> consisting of:</p>
<ol>
    <li>A selector that uniquely identifies the <a href="#dfn-shadow-host">shadow host</a> of this <a href="#dfn-shadow-tree">shadow tree</a></li>
    <li>A combinator that expresses the relationship between an <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> that is either a parent of another <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> <em>or</em> between an <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a>, <a href="#dfn-distribution">distributed</a> into an <a href="#dfn-insertion-point">insertion point</a> and this <a href="#dfn-insertion-point">insertion point</a>'s  parent <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a></li>
    <li>The <a href="#dfn-selector-fragment">selector fragment</a>.</li>
</ol>

<p>A <dfn id="dfn-valid-selector-fragment">valid selector fragment</dfn> may contain:</p>

<ul>
    <li>A <a target='_blank' href="http://www.w3.org/TR/css3-selectors/#type-selectors">type selector</a> or a <a target='_blank' href="http://www.w3.org/TR/css3-selectors/#universal-selector">universal selector</a></li>
    <li><a target='_blank' href="http://www.w3.org/TR/css3-selectors/#class-html">class selector(s)</a></li>
    <li>An <a target='_blank' href="http://www.w3.org/TR/css3-selectors/#id-selectors">ID selector</a></li>
    <li><a target='_blank' href="http://www.w3.org/TR/css3-selectors/#attribute-selectors">attribute selector(s)</a></li>
    <li>the following <a target='_blank' href="http://www.w3.org/TR/css3-selectors/#pseudo-classes">pseudo-class selector(s)</a>:
        <ul>
            <li><code>:link</code></li>
            <li><code>:visited</code></li>
            <li><code>:target</code></li>
            <li><code>:enabled</code></li>
            <li><code>:disabled</code></li>
            <li><code>:checked</code></li>
            <li><code>:indeterminate</code></li>
            <li><code>:nth-child()</code></li>
            <li><code>:nth-last-child()</code></li>
            <li><code>:nth-of-type()</code></li>
            <li><code>:nth-last-of-type()</code></li>
            <li><code>:first-child</code></li>
            <li><code>:last-child</code></li>
            <li><code>:first-of-type</code></li>
            <li><code>:last-of-type</code></li>
            <li><code>:only-of-type</code></li>
        </ul>
    </li>
</ul>

<p>If any other types of selectors are present in the <a href="#dfn-selector-fragment">selector fragment</a>, the fragment <strong>must</strong> be considered invalid.</p>

<p>A conforming UAs <strong>must</strong> consider a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> as <dfn id="#dfn-content-matching">matching</dfn> a set of <a href="#dfn-selector-fragment">selector fragments</a> in the context of a given <a href="#dfn-shadow-host">shadow host</a>, if:
<ol>
    <li>all <a href="#dfn-selector-fragment">selector fragments</a> in the set are <a href="#dfn-valid-selector-fragment">valid</a>; and</li>
    <li>child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> matches at least one selector fragment in the set or the set is empty.</li>
</ol>

<h3 id="selecting-nodes-distributed-to-insertion-points">Matching Children, Distributed To Insertion Points</h3>

<p><a target='_blank' href="http://dev.w3.org/csswg/selectors4/#idref-combinators">Reference combinators</a> match the children of a <a href="#dfn-shadow-host">shadow host</a>, <a href="#dfn-distribution">distributed</a> to the <a href="#dfn-insertion-point">insertion points</a> within a <a href="#dfn-shadow-tree">shadow tree</a>. To match, all of these conditions <strong>must</strong> apply:</p>
<ul>
    <li>The combinator value <strong>must</strong> be <code>select</code></li>
    <li>The first compound selector of the combinator <strong>must</strong> match an <a href="#dfn-insertion-point">insertion point</a></li>
    <li>The second compound selector <strong>must</strong> match an <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a>, <a href="#dfn-distribution">distributed</a> to this <a href="#dfn-insertion-point">insertion point</a></li>
</ul>
<p>For example, <code class="prettify">.some-insertion-point /select/ div.special</code> will match all <code>div</code> <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a> that have <code>class</code> attribute set to <code>special</code> and have been <a href="#dfn-distribution">distributed</a> to an insertion point that has a class attribute set to <code>some-insertion-point</code>.</p>

<p>All other types of selectors <strong>must not</strong> cross the <a href="#dfn-shadow-boundary">shadow boundary</a> from a <a href="#dfn-shadow-tree">shadow tree</a> to the <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> of its <a href="#dfn-shadow-host">shadow host</a>.</p>


<h3 id="multiple-shadow-trees">Hosting Multiple Shadow Trees</h3>

<p>A <a href="#dfn-shadow-host">shadow host</a> may host more than one <a href="#dfn-shadow-tree">shadow tree</a>. In such cases, the trees are stacked in the order they were added the host, starting with the <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> added most recently. This set of trees is called a <dfn id="dfn-tree-stack">tree stack</dfn>. The more recently added <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> is called the <dfn id="dfn-younger-tree">younger tree</dfn>, and the less recently added <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> is called the <dfn id="dfn-older-tree">older tree</dfn>. The most recently added <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> is called the <dfn id="dfn-youngest-tree">youngest tree</dfn>.</p>

<p>To facilitate composing multiple shadow trees of the same host, a special kind of <a href="#dfn-insertion-point">insertion point</a> is defined. The <dfn id="dfn-shadow-insertion-point">shadow insertion point</dfn> designates a place in the <a href="#dfn-shadow-tree">shadow tree</a>, where an <a href="#dfn-older-tree">older tree</a> is inserted when rendering. If multiple <a href="#dfn-shadow-insertion-point">shadow insertion points</a> exist in a <a href="#dfn-shadow-tree">shadow tree</a>, only the first, in <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#tree-order">tree order</a>, is recognized. It is said that the <a href="#dfn-shadow-tree">shadow tree</a> is <dfn id="dfn-assigned">assigned</dfn> to a <a href="#dfn-shadow-insertion-point">shadow insertion point</a> if the <a href="#dfn-shadow-tree">shadow tree</a> is rendered in place of this <a href="#dfn-shadow-insertion-point">shadow insertion point</a>.</p>

<p>Just like other <a href="#dfn-insertion-point">insertion points</a>, the <a href="#dfn-shadow-insertion-point">shadow insertion points</a> can be <a href="#dfn-active-insertion-point">active</a> or <a href="#dfn-inactive-insertion-point">inactive</a>.</p>

<h3 id="reprojection">Reprojection</h3>

<p>One case that deserves special consideration is the situation when an <a href="#dfn-insertion-point">insertion point</a> is a child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> of another <a href="#dfn-shadow-host">shadow host</a>. In such situations, the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> <a href="#dfn-distribution">distributed</a> into that <a href="#dfn-insertion-point">insertion point</a> <strong>must</strong> appear as if they were child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> of the <a href="#dfn-shadow-host">shadow host</a> in the context of <a href="#dfn-distribution">distribution</a> within the <a href="#dfn-shadow-tree">shadow tree</a>, hosted by said <a href="#dfn-shadow-host">shadow host</a>. Thus, the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> <a href="#dfn-distribution">distributed</a> to a <a href="#dfn-shadow-tree">shadow tree</a> could have already been <a href="#dfn-distribution">distributed</a> by the <a href="#dfn-nesting-tree">nesting</a> tree. The effect of a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> being <a href="#dfn-distribution">distributed</a> into more than one <a href="#dfn-insertion-point">insertion point</a> is called <dfn id="dfn-reprojection">reprojection</a>.</p>

<div class="informative">
Despite being distributed to more than one insertion point during reprojection, a node is still only rendered once, because of the constraints under which the reprojection occurs: since the insertion points are only subject to reprojection when they are children of a shadow host, they are never rendered. Instead the shadow tree is rendered in their place.
</div>

<h3 id="composition">Composition</h3>

<p>The composition of <a href="#dfn-shadow-tree">shadow trees</a> for a given <a href="#dfn-shadow-host">shadow host</a> is performed with the <dfn id="dfn-tree-composition">tree composition algorithm</dfn>, which <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:


<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>HOST</var>, a <a href="#dfn-shadow-host">shadow host</a></dd>
<dt>Output</dt>
    <dd>All <a href="#dfn-insertion-point">insertion points</a> and <a href="#dfn-shadow-insertion-point">shadow insertion points</a> are populated.</dd>
</dl>

<ol>
    <li>Let <var>TREE</var> be the <a href="#dfn-youngest-tree">youngest tree</a> in the <var>HOST</var>'s <a href="#dfn-tree-stack">tree stack</a>
    <li>Let <var>POOL</var> be an empty list of nodes</li>
    <li>For each child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> of <var>HOST</var>:
    <ol>
        <li>Let <var>CHILD</var> be this node</li>
        <li>If <var>CHILD</var> is an <a href="#dfn-insertion-point">insertion point</a>:
        <ol>
            <li>Let <var>REPROJECTED</var> be the list of nodes, distributed into this <a href="#dfn-insertion-point">insertion point</a> as a result of running <a href="#dfn-tree-composition">tree composition algorithm</a> on this <a href="#dfn-insertion-point">insertion point</a>'s <a href="#dfn-shadow-tree">shadow tree</a></li>
            <li>If <var>REPROJECTED</var> is an empty list, set it to the list of all child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> of <var>CHILD</var>
            <li>Add all <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> in <var>REPROJECTED</var> into <var>POOL</var></li>
        </ol></li>
        <li>Otherwise, add <var>CHILD</var> to <var>POOL</var></li>
    </ol></li>
    <li><dfn id="algo-composition-repeat">Repeat</dfn> while <var>TREE</var> exists:
    <ol>
        <li>Let <var>POINT</var> be the first encountered <a href="#dfn-active-insertion-point">active</a> <a href="#dfn-shadow-insertion-point">shadow insertion point</a> in <var>TREE</var>, in <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#tree-order">tree order</a>
        <li>Run the <a href="#dfn-distribution-algorithm">distribution algorithm</a>, supplying <var>POOL</var> and <var>TREE</var> as input</li>
        <li>If <var>POINT</var> exists:
        <ol>
            <li>Find the next older tree, relative to <var>TREE</var> in the <var>HOST</var>'s <a href="#dfn-tree-stack">tree stack</a>
            <ol>
                <li>If there is no older tree, <strong>stop</strong>.</li>
                <li>Otherwise:
                <ol>
                    <li>Set <var>TREE</var> to be this older tree</li>
                    <li><a href="#dfn-assigned">Assign</a> <var>TREE</var> to the <var>POINT</var></li>
                    <li>Continue to <a href="#algo-composition-repeat">repeat</a></li>
                </ol></li>
            </ol></li>
        </ol></li>
        <li>Otherwise, <strong>stop</strong>.
    </ol></li>
</ol>
</div>

<p>When an <a href="#dfn-insertion-point">insertion point</a> or a <a href="#dfn-shadow-insertion-point">shadow insertion point</a> has nothing <a href="#dfn-assigned">assigned</a> or <a href="#dfn-distribution">distributed</a> to them, the fallback content <strong>must</strong> be used instead when rendering. The <dfn id="dfn-fallback-content">fallback content</dfn> is all descendants of the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> that represents the insertion point. The <a href="#dfn-insertion-point">insertion points</a> or <a href="#dfn-shadow-insertion-point">shadow insertion points</a> in fallback content <strong>must</strong> be considered <a href="#dfn-inactive-insertion-point">inactive</a>.</p>

<h3 id="nested-shadow-trees">Nested Shadow Trees</h3>

<p>Any <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> in a <a href="#dfn-shadow-tree">shadow tree</a> can be a <a href="#dfn-shadow-host">shadow host</a>, thus producing nested <a href="#dfn-shadow-tree">shadow trees</a>. A <a href="#dfn-shadow-tree">shadow tree</a> is <dfn id="dfn-nested-tree">nested</dfn> when its <a href="#dfn-shadow-host">shadow host</a> is itself a part of a <a href="#dfn-shadow-tree">shadow tree</a>. Conversely, a <a href="#dfn-shadow-tree">shadow tree</a> <em>A</em> is said to be <dfn id="dfn-nesting-tree">nesting</dfn> the <a href="#dfn-shadow-tree">shadow tree</a> <em>B</em> if <em>B</em> is <a href="#dfn-nested-tree">nested</a> by <em>A</em>. If a <a href="#dfn-shadow-host">shadow host</a> is declared in the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a>, the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a> is the <a href="#dfn-nesting-tree">nesting</a> <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> of its <a href="#dfn-shadow-tree">shadow trees</a>.</p>

<p>A <a href="#dfn-shadow-tree">shadow tree</a> is <dfn id="dfn-enclosed-tree">enclosed</dfn> by another <a href="#dfn-shadow-tree">shadow tree</a> when the enclosing <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> nests the enclosed <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> through one or more levels of nesting. All <a href="#dfn-shadow-tree">shadow trees</a> are <a href="#dfn-enclosed-tree">enclosed</a> by the <a href="#dfn-document-tree">document tree</a>.</p>

<h3 id="rendering-shadow-trees">Rendering Shadow Trees</h3>

<p><dfn id="dfn-rendering">Rendering</dfn> of <a href="#dfn-shadow-tree">shadow trees</a>, or presenting them visually, is defined as a specialization of rendering <strong>any DOM tree</strong>, and <strong>must</strong> happen as these steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>HOST</var>, a <a href="#dfn-shadow-host">shadow host</a></dd>
<dt>Output</dt>
    <dd>Rendering of the <var>HOST</var>, including its <a href="#dfn-shadow-tree">shadow trees</a></dd>
</dl>

<ol>
    <li>Run <a href="#dfn-tree-composition">tree composition algorithm</a> for the given <a href="#dfn-shadow-host">shadow host</a></li>
    <li>As content of the <a href="#dfn-shadow-host">shadow host</a>, render the <a href="#dfn-youngest-tree">youngest tree</a> as a <strong>any DOM tree</strong>, with the following <dfn id="dfn-shadow-rendering">shadow rendering</dfn> exceptions:
    <ul>
        <li>Each <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> that is a <a href="#dfn-shadow-host">shadow host</a> <strong>must</strong> be <a href="#dfn-rendering">rendered</a> accordingly</li>
        <li>In place of each <a href="#dfn-insertion-point">insertion point</a>, process the following <dfn id="dfn-insertion-point-rendering">insertion point rendering</dfn> steps:
        <ol>
            <li>If there are child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> <a href="#dfn-distribution">distributed</a> to this insertion point, for each child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> and in the order they were distributed:
            <ol>
                <li>Let <var>CHILD</var> be the child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> being rendered</li>
                <li>If <var>CHILD</var> is itself an <a href="#dfn-insertion-point">insertion point</a>, and the <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> being rendered is <a href="#dfn-nested-tree">nested</a>, render them using <a href="#dfn-insertion-point-rendering">insertion point rendering</a> steps</li>
                <li>Otherwise, render <var>CHILD</var> as <strong>any DOM tree</strong>
            </ol></li>
            <li>Otherwise, render <a href="#dfn-fallback-content">fallback content</a> as <strong>any DOM tree</strong></li>
        </ol></li>
        <li>In place of each <a href="#dfn-shadow-insertion-point">shadow insertion point</a>:
        <ol>
            <li>If there is an <a href="#dfn-older-tree">older tree</a>, <a href="#dfn-assigned">assigned</a> to this shadow insertion point, render it as <strong>any DOM tree</strong>, but with the same <a href="#dfn-shadow-rendering">shadow rendering</a> exceptions.</li>
            <li>Otherwise, render <a href="#dfn-fallback-content">fallback content</a> as <strong>any DOM tree</strong></li>
        </ol></li>
    </ul></li>
</ol>
</div>

<p>This process of <a href="#dfn-rendering">rendering</a> produces a structure that is a composition of several <a target='_blank' href="http://www.w3.org/TR/domcore/#introduction-to-the-dom">DOM</a> trees, including the <a href="#dfn-document-tree">document tree</a>. The term "<dfn id="dfn-as-rendered">as rendered</dfn>" is used to refer to this structure.</p>

<h3 id="custom-pseudo-elements">Custom Pseudo-Elements</h3>

<p>In certain situations, the author of a <a href="#dfn-shadow-tree">shadow tree</a> may wish to designate one or more <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a> from that <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> as a structural abstraction that provides additional information about the contents of the <a href="#dfn-shadow-tree">shadow tree</a>.</p>

<div class="informative">
For example, when developing a 2-dimensional range slider widget, which offers a thumb that could be moved in 2 directions in a rectangular space, the author decides to allow the widget users to style the thumb directly.
</div>

<p>The <dfn id="dfn-custom-pseudo-element">custom pseudo-elements</dfn> enable this scenario. A <a href="#dfn-custom-pseudo-element">custom pseudo-element</a> is an association between an <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> in a <a href="#dfn-shadow-tree">shadow tree</a> and a string value. This string value is called a <dfn id="dfn-custom-pseudo-element-value">custom pseudo-element value</dfn>. The <a href="#dfn-custom-pseudo-element-value">custom pseudo-element value</a> <strong>must</strong> be considered <dfn id="dfn-valid-custom-pseudo-element-value">valid</dfn> if it starts with a <var>U+0078 LATIN SMALL LETTER X</var>, followed by  <var>U+002D HYPHEN-MINUS</var>. Otherwise, the <a href="#dfn-custom-pseudo-element-value">custom pseudo-element value</a> <strong>must</strong> be considered invalid.</p>

<div class="informative">

<p>In the case of the aforementioned 2-dimensional slider widget, the author could build the widget's shadow tree as follows:</p>

<pre><code class="prettyprint">
var widget = document.createElement('div');
var root = widget.createShadowRoot();
var thumb = document.createElement('div');
thumb.pseudo = 'x-thumb';
root.appendChild(thumb);
</code></pre>

<p>Once the <code>pseudo</code> property is set, the consumer of the widget could style the widget's thumb using <code>x-thumb</code> pseudo-element, reaching into the widget's shadow tree directly to the thumb:</p>

<pre><code class="prettyprint">
div::x-thumb {
    width: 10px;
    height: 10px;
    color: bisque;
}
</pre></code>

</div>

<h2 id="events">Events</h2>

<p>When an <a target='_blank' href="http://www.w3.org/TR/domcore/#events">event</a> is <a target='_blank' href="http://www.w3.org/TR/domcore/#dispatching-events">dispatched</a> in a <a href="#dfn-shadow-tree">shadow tree</a>, its path either crosses the <a href="#dfn-shadow-boundary">shadow boundary</a> or is terminated at the <a href="#dfn-shadow-boundary">shadow boundary</a>. One exception are the mutation events. The <a target='_blank' href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-eventgroupings-mutationevents">mutation event types</a> <strong>must</strong> never be dispatched in a <a href="#dfn-shadow-tree">shadow tree</a>.</p>

<p>For event path to cross the <a href="#dfn-shadow-boundary">shadow boundary</a>, it <strong>must</strong> be populated with <dfn id="dfn-adjusted-parent">adjusted parents</dfn>, or <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> that appear as parents <a href="#dfn-as-rendered">as rendered</a>. The <dfn id="dfn-parent-calculation-algorithm">parent calculation algorithm</dfn> is used to determine the <a href="#dfn-adjusted-parent">adjusted parent</a> of any given <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> and create the list of ancestors for event dispatch. This algorithm <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>NODE</var>, a node</dd>
    <dd><var>CONTEXT</var>, <strong>null</strong> or a <a href="#dfn-reprojection">reprojection</a> context node</dd>
<dt>Output</dt>
    <dd><var>PARENT</var>, a node's <a href="#dfn-adjusted-parent">adjusted parent</a></dd>
</dl>
<ol>
    <li>If <var>NODE</var> is a <a href="#dfn-shadow-root">shadow root</a>:
    <ol>
        <li>If <var>NODE</var> is currently <a href="#dfn-assigned">assigned</a> to a <a href="#dfn-shadow-insertion-point">shadow insertion point</a>:
        <ol>
            <li>Let the <var>PARENT</var> be the <a href="#dfn-shadow-insertion-point">shadow insertion point</a> to which <var>NODE</var> is <a href="#dfn-assigned">assigned</a> to</li>
        </ol></li>
        <li>Otherwise, let the <var>PARENT</var> be the <a href="#dfn-shadow-host">shadow host</a> of the <var>NODE</var>
    </ol></li>
    <li>If <var>NODE</var> is currently <a href="#dfn-distribution">distributed</a> to an <a href="#dfn-insertion-point">insertion point</a> in a <a href="#dfn-shadow-tree">shadow tree</a>, let <var>PARENT</var> be the <a href="#dfn-insertion-point">insertion point</a> to which the <var>NODE</var> is <a href="#dfn-distribution">distributed</a></li>
    <li>If <var>NODE</var> is an <a href="#dfn-insertion-point">insertion point</a> and <var>CONTEXT</var> is not <strong>null</strong>:
    <ol>
      <li>If the parent <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> of <var>NODE</var> is a <a href="#dfn-shadow-host">shadow host</a> <em>and</em> its <a href="#dfn-shadow-tree">shadow tree</a> contains an <a href="#dfn-insertion-point">insertion point</a> to which <var>CONTEXT</var> is <a href="#dfn-distribution">distributed</a>, let <var>PARENT</var> be that <a href="#dfn-insertion-point">insertion point</a></li>
    </ol></li>
    <li>Otherwise, let <var>PARENT</var> be the node's parent node.</li>
</ol>
</div>

<h3 id="event-retargeting">Event Retargeting</h3>

<p>In the cases where events cross the <a href="#dfn-shadow-boundary">shadow boundaries</a>, the event's information about the target of the event is adjusted in order to maintain <a href="#dfn-upper-boundary-encapsulation">upper boundary encapsulation</a>. Event <dfn id="dfn-retargeting">retargeting</dfn> is a process of computing relative targets for each ancestor of the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> at which the event is dispatched. A <dfn id="dfn-relative-target">relative target</dfn> is a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> that most accurately represents the target of a dispatched event at a given ancestor while maintaining the <a href="#dfn-upper-boundary-encapsulation">upper boundary encapsulation</a>.

<p>The <dfn id="dfn-retargeting-algorithm">retargeting algorithm</dfn> is used to determine relative targets, and it <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>NODE</var>, a node</dd>
<dt>Output</dt>
    <dd><var>TARGETS</var>, a list of tuples, each containing <var>NODE</var>'s ancestor and its relative target</dd>
</dl>
<ol>
    <li>Let <var>STACK</var> be a stack of nodes</li>
    <li>Let <var>ANCESTOR</var> be <var>NODE</var></li>
    <li><dfn id="algo-reatargeting-repeat">Repeat</dfn> while <var>ANCESTOR</var> exists:
    <ol>
        <li>If <var>ANCESTOR</var> is an <a href="#dfn-insertion-point">insertion point</a>:
        <ol>
            <li>Let <var>CONTEXT</var> be the top-most item in <var>STACK</var> that is not an <a href="#dfn-insertion-point">insertion point</a> or <strong>null</strong> if such item does not exist.</li>
            <li>Let <var>TOP</var> be the item at the top of <var>STACK</var>, or <var>ANCESTOR</var> if <var>STACK</var> is empty</li>
            <li>Push <var>TOP</var> into <var>STACK</var></li>
        </ol></li>
        <li>Otherwise, let <var>CONTEXT</var> be <strong>null</strong></li>
        <li>If <var>STACK</var> is empty, push <var>ANCESTOR</var> into <var>STACK</var></li>
        <li>Let <var>TARGET</var> be the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> at the top of <var>STACK</var></li>
        <li>Add (<var>TARGET</var>, <var>ANCESTOR</var>) tuple to <var>TARGETS</var></li>
        <li>If <var>ANCESTOR</var> is a <a href="#dfn-shadow-root">shadow root</a>:
        <ol>
            <li>Pop <var>STACK</var>, if <var>STACK</var> is not empty</li>
        </ol></li>
        <li>Set <var>ANCESTOR</var> to be the result of <a href="#dfn-parent-calculation-algorithm">parent calculation algorithm</a>, given <var>ANCESTOR</var> and <var>CONTEXT</var> as input</li>
    </ol></li>
</ol>
</div>

<p>The retargeting process <strong>must</strong> occur prior to dispatch of an event.</p>

<h3 id="retargeting-related-target">Retargeting <code>relatedTarget</code></h3>

<p>Some events have a <a target='_blank' href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> property, which holds a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> that's not the event's target, but is related to the event.</p>

<p>For instance, a <code>mouseover</code> event's <a target='_blank' href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> may hold the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> from which the mouse has moved to event's <code>target</code>. In the case where <code>relatedTarget</code> is in a <a href="#dfn-shadow-tree">shadow tree</a>, the conforming UAs <strong>must</strong> not leak its actual value outside of this tree. In cases where both <code>relatedTarget</code> and <code>target</code> are part of the same <a href="#dfn-shadow-tree">shadow tree</a>, the conforming UAs <strong>must</strong> <em>stop</em> events at the <a href="#dfn-shadow-boundary">shadow boundary</a> to avoid the appearance of spurious <code>mouseover</code> and <code>mouseout</code> events firing from the same node.</p>

<p>Thus, if an event has a <code>relatedTarget</code>, its value and extent of event dispatch <strong>must</strong> be adjusted. In general:</p>
<ol>
    <li>For a given node, the <code>relatedTarget</code> <strong>must</strong> be changed to its ancestor (or self) that is in the same <a href="#dfn-shadow-tree">shadow tree</a> as the node</li>
    <li>Event listeners <strong>must not</strong> be invoked on a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> for which the <code>target</code> and <code>relatedTarget</code> are the same.</li>
</ol>

<p>The <dfn id="dfn-related-target-algorithm">related target resolution</dfn> algorithm <strong>must</strong> be used to determine the value of the <a target='_blank' href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> property and <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>NODE</var>, the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> on which event listeners would be invoked</dd>
    <dd><var>RELATED</var>, the related target for the event</dd>
<dt>Output</dt>
    <dd><var>ADJUSTED</var>, the <dfn id="dfn-adjusted-related-target">adjusted related target</dfn> for <var>NODE</var></dd>
</dl>
<ol>
    <li>Let <var>TARGET</var> be <var>NODE</var></li>
    <li>Let <var>ADJUSTED</var> be <strong>undefined</strong></li>
    <li><dfn id="algo-target-repeat">Repeat</dfn> while <var>TARGET</var> exists:
    <ol>
        <li>Let <var>STACK</var> be an empty stack of nodes</li>
        <li>Let <var>ANCESTOR</var> be <var>RELATED</var></li>
        <li>Let <var>LAST</var> be <strong>undefined</strong></li>
        <li><dfn id="algo-ancestor-repeat">Repeat</dfn> while <var>ANCESTOR</var> exists:
        <ol>
            <li>Let <var>CONTEXT</var> be <strong>null</strong>
            <li>If <var>STACK</var> is empty, push <var>ANCESTOR</var> into <var>STACK</var></li>
            <li>Otherwise, if <var>ANCESTOR</var> is an <a href="#dfn-insertion-point">insertion point</a>:
            <ol>
                <li>Let <var>CONTEXT</var> be the top-most item that is not an <a href="#dfn-insertion-point">insertion point</a> in <var>STACK</var> or <strong>null</strong>, if such item does not exist.</li>
                <li>If <var>LAST</var> is <a href="#dfn-distribution">distributed</a> or assigned into <var>ANCESTOR</var>:
                <ol>
                    <li>Let <var>HEAD</var> be the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> at the top of the <var>STACK</var></li>
                    <li>Push <var>HEAD</var> into <var>STACK</var></li>
                </ol></li>
            </ol></li>
            <li>If <var>ANCESTOR</var> and <var>TARGET</var> are in the same tree:
            <ol>
                <li>Let <var>ADJUSTED</var> be the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> at the top of the stack</li>
                <li><strong>Stop.</strong></li>
            </ol></li>
            <li>If <var>ANCESTOR</var> is a <a href="#dfn-shadow-root">shadow root</a>, pop <var>STACK</var></li>
            <li>Let <var>LAST</var> be <var>ANCESTOR</var></li>
            <li>Set <var>ANCESTOR</var> to be the result of <a href="#dfn-parent-calculation-algorithm">parent calculation algorithm</a>, given <var>ANCESTOR</var> and <var>CONTEXT</var> as input</li>
        </ol></li>
        <li>If <var>TARGET</var> is a <a href="#dfn-shadow-root">shadow root</a>, let <var>TARGET</var> be the <a href="#dfn-shadow-host">shadow host</a> of <var>TARGET</var></li>
        <li>Otherwise, let <var>TARGET</var> be <var>TARGET</var>'s parent node</li>
    </ol></li>
</ol>
</div>

<h3 id="retargeting-focus-events">Retargeting Focus Events</h3>

<p>The <code>focus</code>, <code>DOMFocusIn</code>, <code>blur</code>, and <code>DOMFocusOut</code> events <strong>must</strong> be treated in the same way as events with a <code>relatedTarget</code>, where the corresponding <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> that is losing focus as a result of <code>target</code> gaining focus or the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> that is gaining focus, and thus causing the blurring of <code>target</code> acts as the related target.</p>

<h3 id="events-that-are-always-stopped">Events that are Always Stopped</h3>

<p>The following events <strong>must</strong> always be stopped at the nearest <a href="#dfn-shadow-boundary">shadow boundary</a>:</p>
<ul>
    <li><code>abort</code></li>
    <li><code>error</code></li>
    <li><code>select</code></li>
    <li><code>change</code></li>
    <li><code>load</code></li>
    <li><code>reset</code></li>
    <li><code>resize</code></li>
    <li><code>scroll</code></li>
    <li><code>selectstart</code></li>
</ul>

<h3 id="event-dispatch">Event Dispatch</h3>

<p>At the time of event dispatch:</p>
<ul>
    <li>The <a target='_blank' href="http://www.w3.org/TR/domcore/#event"><code>Event</code></a> <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-event-target"><code>target</code></a> and <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-event-currenttarget"><code>currentTarget</code></a> attributes <strong>must</strong> return the <a href="#dfn-relative-target">relative target</a> for the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> on which event listeners are <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-event-listener-invoke">invoked</a></li>
    <li>The <a target='_blank' href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent"><code>MouseEvent</code></a> <a target='_blank' href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> attribute <strong>must</strong> return the <a href="#dfn-adjusted-related-target">adjusted related target</a></li>
    <li>The <a target='_blank' href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent"><code>MouseEvent</code></a> <a target='_blank' href="http://dev.w3.org/csswg/cssom-view/#widl-MouseEvent-offsetX"><code>offsetX</code></a> and <a target='_blank' href="http://dev.w3.org/csswg/cssom-view/#widl-MouseEvent-offsetY"><code>offsetY</code></a> attributes <strong>must</strong> return the coordinates relative to the origin of the <a target='_blank' href="http://dev.w3.org/csswg/cssom-view/#padding-edge">padding edge</a> of the <a href="#dfn-relative-target">relative target</a></li>
    <li>If the <a target='_blank' href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> and <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-event-target"><code>target</code></a> are the same for a given node, its the event listeners <strong>must not</strong> be invoked</li>
    <li>When <em>capturing</em>, which entails processing step 3 of the <a target='_blank' href="http://www.w3.org/TR/domcore/#dispatching-events">event dispatch algorithm</a>, the <a target='_blank' href="http://www.w3.org/TR/domcore/#event"><code>Event</code></a> <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-event-eventphase">eventPhase</a> attribute <strong>must</strong> return <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-event-at_target">AT_TARGET</a> <strong>if</strong> the <a href="#dfn-relative-target">relative target</a> is same as the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> on which event listeners are <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-event-listener-invoke">invoked</a></li>
    <li>When <em>bubbling</em>, which entails processing step 6 of the <a target='_blank' href="http://www.w3.org/TR/domcore/#dispatching-events">event dispatch algorithm</a>, the event listeners <strong>must not</strong> be <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-event-listener-invoke">invoked</a> on a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> <strong>if</strong> it is the same as its <a href="#dfn-relative-target">relative target</a></li>
</ul>

<p>Upon completion of the event dispatch, the <a target='_blank' href="http://www.w3.org/TR/domcore/#event"><code>Event</code></a> object's <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-event-target"><code>target</code></a> and <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-event-currenttarget"><code>currentTarget</code></a> <strong>must</strong> be to the highest ancestor's <a href="#dfn-relative-target">relative target</a>. Since it is possible for a script to hold on to the <code>Event</code> object past the scope of event dispatch, this step is necessary to avoid revealing the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> in <a href="#dfn-shadow-tree">shadow trees</a>.</p>

<h3 id="event-retargeting-example">Event Retargeting Example</h3>

<p>Suppose we have a user interface for a media controller, represented by this tree, composed of both <a href="#dfn-document-tree">document tree</a> and the <a href="#dfn-shadow-tree">shadow trees</a>. In this example, we will assume that selectors are allowed to cross the shadow boundaries and we will use these selectors to identify the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a>. Also, we will invent a fictional <code>shadow-root</code> <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> to demarcate the <a href="#dfn-shadow-boundary">shadow boundaries</a> and represent <a href="#dfn-shadow-root">shadow roots</a>:</p>
<pre><code>
&lt;div id=&quot;player&quot;&gt;
    <span class=shadow-boundary>&lt;shadow-root id=&quot;player-shadow-root&quot;&gt;</span>
        &lt;div id=&quot;controls&quot;&gt;
            &lt;button class=&quot;play-button&quot;&gt;PLAY&lt;/button&gt;
            &lt;input type=&quot;range&quot; id=&quot;timeline&quot;&gt;
                <span class=shadow-boundary>&lt;shadow-root id=&quot;timeline-shadow-root&quot;&gt;</span>
                    &lt;div class=&quot;slider-thumb&quot; id=&quot;timeline-slider-thumb&quot;&gt;&lt;/div&gt;
                <span class=shadow-boundary>&lt;/shadow-root&gt;</span>
            &lt;/input&gt;
            &lt;div class=&quot;volume-slider-container&quot;&gt;
                &lt;input type=&quot;range&quot; class=&quot;volume-slider&quot;&gt;
                    <span class=shadow-boundary>&lt;shadow-root id=&quot;volume-shadow-root&quot;&gt;</span>
                        &lt;div class=&quot;slider-thumb&quot; id=&quot;volume-slider-thumb&quot;&gt;&lt;/div&gt;
                    <span class=shadow-boundary>&lt;/shadow-root&gt;</span>
                &lt;/input&gt;
            &lt;/div&gt;
        &lt;/div&gt;
    <span class=shadow-boundary>&lt;/shadow-root&gt;</span>
&lt;/div&gt;
</code></pre>

<p>Let's have a user position their pointing device over the volume slider's thumb (<code>#volume-slider-thumb</code>), thus triggering a <code>mouseover</code> event on that node. For this event, let's pretend it has no associated <code>relatedTarget</code>.</p>

<p>Just before the event is dispatched, we perform <a href="#dfn-retargeting">retargeting</a>:</p>
<ol>
    <li>Since <code>#volume-slider-thumb</code> is not an <a href="#dfn-insertion-point">insertion point</a>, we push it onto <var>STACK</var>, and add the first tuple to <var>TARGETS</var> as (<code>#volume-slider-thumb</code>, <code>#volume-slider-thumb</code>)</li>
    <li>We then <a href="#dfn-parent-calculation-algorithm">calculate parent</a> as <code>#volume-shadow-root</code> and proceed to second iteration, adding (<code>#volume-slider-thumb</code>, <code>#volume-shadow-root</code>) tuple to <var>TARGETS</var></li>
    <li>Because <code>#volume-shadow-root</code> is a <a href="#dfn-shadow-root">shadow root</a>, we pop <var>STACK</var>, thus emptying it</li>
    <li>Next <a href="#dfn-parent-calculation-algorithm">parent calculation</a> yields <code>#volume-slider</code>, and so we begin the third iteration</li>
    <li>Here, <var>STACK</var> is empty again, so we push <code>#volume-slider</code> into it and add (<code>#volume-slider</code>, <code>#volume-slider</code>) to <var>TARGETS</var></li>
    <li>The <a href="#dfn-parent-calculation-algorithm">parent</a> of <code>#volume-slider</code> is <code>#volume-slider-container</code> not a <a href="#dfn-shadow-root">shadow root</a> and not an <a href="#dfn-insertion-point">insertion point</a>, which dictates that we add (<code>#volume-slider</code>, <code>#volume-slider-container</code>) to <var>TARGETS</var></li>
    <li>Next <a href="#dfn-parent-calculation-algorithm">up</a>, we see <code>#controls</code>, again neither a <a href="#dfn-shadow-root">shadow root</a> nor an <a href="#dfn-insertion-point">insertion point</a>, which means we add (<code>##volume-slider</code>, <code>#controls</code>) to <var>TARGETS</var></li>
    <li>The <a href="#dfn-parent-calculation-algorithm">next ancestor</a> is <code>#player-shadow-root</code>, a <a href="#dfn-shadow-root">shadow root</a>, and thus we add it (<code>#volume-slider</code>, <code>#player-shadow-root</code>) to <var>TARGETS</var>, then pop <var>STACK</var>, emptying it</li>
    <li>Its <a href="#dfn-parent-calculation-algorithm">parent</a> is <code>#player</code>, neither <a href="#dfn-shadow-root">shadow root</a> nor <a href="#dfn-insertion-point">insertion point</a>, and <var>STACK</var> is empty, so we push <code>#player</code> to <var>STACK</var>, then add (<code>#player</code>, <code>#player</code>) to <var>TARGETS</var></li>
    <li>In our example, there are no further <a href="#dfn-parent-calculation-algorithm">parents</a>, causing us to exit the <a href="#algo-reatargeting-repeat">loop</a> and stop.</li>
</ol>

<p>At the end of this process, we should have the following set of ancestors and relative targets:</p>
<table>
<thead>
<tr>
    <th>Ancestor</th>
    <th>Relative Target</th>
</tr>
</thead>
<tbody>
<tr>
    <td><code>#player</code></td>
    <td><code><strong>#player</strong></code></td>
</tr>
<tr>
    <td><code>#player-shadow-root</code></td>
    <td><code>#volume-slider</code></td>
</tr>
<tr>
    <td><code>#controls</code></td>
    <td><code>#volume-slider</code></td>
</tr>
<tr>
    <td><code>#volume-slider-container</code></td>
    <td><code>#volume-slider</code></td>
</tr>
<tr>
    <td><code>#volume-slider</code></td>
    <td><code><strong>#volume-slider</strong></code></td>
</tr>
<tr>
    <td><code>#volume-shadow-root</code></td>
    <td><code>#volume-slider-thumb</code></td>
</tr>
<tr>
    <td><code>#volume-slider-thumb</code></td>
    <td><code><strong>#volume-slider-thumb</strong></code></td>
</tr>
</tbody>
</table>

<p>After we dispatch the <code>mouseover</code> event using these newly computed relative targets, the user decides to move their pointing device over the thumb of the timeline
(<code>#timeline-slider-thumb</code>). This triggers both a <code>mouseout</code> event for the volume slider thumb and the <code>mouseover</code> event for the timeline thumb.</p>

<p>Let's study how the <code>relatedTarget</code> value of the volume thumb's <code>mouseout</code> event is affected. For this event, the <code>relatedTarget</code> is the timeline thumb (<code>#timeline-slider-thumb</code>). Per <a href="#dfn-related-target-algorithm">algorithm</a>:</p>

<ol>
    <li>Starting with <var>NODE</var> as <code>#volume-slider-thumb</code> and <var>RELATED</var> as <code>#timeline-slider-thumb</code>,</li>
    <li>We <a href="#algo-ancestor-repeat">examine</a> ancestors of <var>RELATED</var>:
    <ol>
        <li>First <a href="#dfn-parent-calculation-algorithm">up</a> is <code>#timeline-slider-thumb</code>, and we push it into <var>STACK</var></li>
        <li>Then it's <code>#timeline-shadow-root</code>, a <a href="#dfn-shadow-root">shadow root</a>, so we pop <var>STACK</var>, emptying it</li>
        <li>Next is <code>#timeline</code>, we push it into <var>STACK</var></li>
        <li>Then comes <code>#controls</code> and after it, <code>#player-shadow-root</code>, a <a href="#dfn-shadow-root">shadow root</a>, so we pop <var>STACK</var>, emptying it</li>
        <li>Final ancestor is <code>#player</code>, we push it into <var>STACK</var></li>
    </ol>
    <li>Set <var>TARGET</var> to <code>#volume-shadow-root</code></li>
    <li>We again <a href="#algo-ancestor-repeat">examine</a> ancestors of <var>RELATED</var> and notice that it produces the same result as our previous such examination</li>
    <li>We then set <var>TARGET</var> to <code>#volume-slider</code> and</li>
    <li>Repeat <a href="#algo-ancestor-repeat">examination</a> of ancestors once more&mdash;and realize that when <var>ANCESTOR</var> value is <code>#timeline</code>, the <var>ANCESTOR</var> and <var>TARGET</var> are in the same tree, and thus</li>
    <li>Return <code>#timeline</code> as the adjusted <code>relatedTarget</code> value.
</ol>

<p>Performing this computation with <var>NODE</var> as <code>#player</code> yields the result of both <code>target</code> and <code>relatedTarget</code> being the same value (<code>#player</code>), which means that we do not dispatch the event on this <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> and its ancestors.</p>

<h2 id="styles">Styles</h2>

<p>Each <a href="#dfn-shadow-root">shadow root</a> has an associated list of zero or more <a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet">style sheets</a>, named <dfn id="dfn-shadow-root-style-sheets">shadow root style sheets</dfn>. This is an ordered list that contains all <a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet">style sheets</a>, associated with the <a href="#dfn-shadow-root">shadow root</a>, in <a target='_blank' href="http://www.w3.org/TR/dom/#concept-tree-order">tree order</a>.</p>

<p>When a <a href="#dfn-shadow-host">shadow host</a> has multiple <a href="#dfn-shadow-root">shadow roots</a>, the <a target='_blank' href="http://dev.w3.org/csswg/css3-cascade/#cascade">cascade order</a> of <a target='_blank' href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rules</a>, defined in <a href="#dfn-shadow-root-style-sheets">shadow roow style sheets</a>, in ascending order of precedence <strong>must</strong> match the order of the <a href="#dfn-tree-stack">tree stack</a>, ending with the <a href="#dfn-youngest-tree">youngest tree</a>.

<p>To enforce <a href="#dfn-upper-boundary-encapsulation">upper-boundary encapsulation</a>, <a target='_blank' href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rules</a> declared in an <a href="#dfn-enclosed-tree">enclosing</a> <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> <strong>must not</strong> apply in a <a href="#dfn-shadow-tree">shadow tree</a>, except when the <dfn id="dfn-apply-author-styles">apply-author-styles</dfn> flag is set for this tree. The flag signals that the rules declared in the <a href="#dfn-enclosed-tree">enclosing</a> trees are applicable in the <a href="#dfn-shadow-tree">shadow tree</a>.</li>

<p>Even when the <a href="#dfn-apply-author-styles">apply-author-styles</a> is set, the <a target='_blank' href="http://www.w3.org/TR/selectors/">selectors</a> still <strong>must not</strong> cross the <a href="#dfn-shadow-boundary">shadow boundary</a> per <a href="#dfn-scoping-constraints">scoping constraints</a>. In other words, with <a href="#dfn-apply-author-styles">apply-author-styles</a> set, the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a> CSS rules only match wholly inside or outside of the <a href="#dfn-shadow-tree">shadow tree</a>.</p>

<p>For the purposes of the <a target='_blank' href="http://dev.w3.org/csswg/css3-cascade/#cascade">cascade order</a>, the  <a target='_blank' href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rules</a> for <a href="#dfn-shadow-tree">shadow trees</a> that have the <a href="#dfn-apply-author-styles">apply-author-styles</a> flag set <strong>must</strong> be treated as <a target='_blank' href="http://www.w3.org/TR/selectors4/#scoping">scoped</a> selectors with <a href="#dfn-shadow-root">shadow root</a> as their scope. In this context, for <a href="#dfn-shadow-tree">shadow trees</a> <em>A</em> and <em>B</em>, the <em>A</em>'s <a href="#dfn-shadow-root">shadow root</a> is treated as <em>descendant</em> of <em>B</em>'s <a href="#dfn-shadow-root">shadow root</a> if <em>A</em> is <a href="#dfn-enclosed-tree">enclosed</a> by <em>B</em>.</p>

<p>If a <a target='_blank' href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rule</a> in a <a href="#dfn-nesting-tree">nesting</a> <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> ends with a <a target='_blank' href="http://www.w3.org/TR/selectors4/#compound">compound selector</a> that contains a <a target='_blank' href="http://www.w3.org/TR/selectors4/#pseudo-elements">pseudo-element</a> whose name equals to a <a href="#dfn-valid-custom-pseudo-element-value">valid</a> <a href="#dfn-custom-pseudo-element-value">value</a> of a <a href="#dfn-custom-pseudo-element">custom pseudo-element</a> that exists in this <a href="#dfn-shadow-tree">shadow tree</a>, this <a target='_blank' href="http://www.w3.org/TR/selectors4/#pseudo-elements">pseudo-element</a> <strong>must</strong> match the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a>, associated with this <a href="#dfn-custom-pseudo-element">custom pseudo-element</a>.</p>

<p>Conversely, to enforce <a href="#dfn-lower-boundary-encapsulation">lower-boundary encapsulation</a>, <a target='_blank' href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rules</a> declared in a <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a> <strong>must not</strong> apply in the <a href="#dfn-document-tree">document tree</a>, with two exceptions:</p>
<ol>
    <li>Rules that contain <code>select</code> <a target='_blank' href="http://dev.w3.org/csswg/selectors4/#idref-combinators">reference combinators</a> match <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a> in the <a href="#dfn-enclosed-tree">enclosing</a> trees;</li>
    <li>The <a href="#host-at-rule"><code>@host</code> @-rule</a> matches a <a href="#dfn-shadow-host">shadow host</a> in the <a href="#dfn-nesting-tree">nesting</a> tree.</li>
</ol>

<p>In a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a> that contains <a href="#dfn-shadow-tree">shadow trees</a>, the CSS properties <strong>must</strong> be inherited from parent nodes, produced using the <a href="#dfn-parent-calculation-algorithm">parent calculation algorithm</a>. This requirement has the following effects:</p>
<ul>
    <li>the styles of the <a href="#dfn-shadow-host">shadow host</a> are inherited by the children of the <a href="#dfn-shadow-root">shadow root</a></li>
    <li>the styles of the <a href="#dfn-insertion-point">insertion point</a> <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> are inherited by those child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> of the <a href="#dfn-shadow-host">shadow host</a> that are <a href="#dfn-assigned">assigned</a> to this <a href="#dfn-insertion-point">insertion point</a></li>
    <li>the styles of the <a href="#dfn-shadow-insertion-point">shadow insertion point</a> <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> are inherited by the child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> of the <a href="#dfn-shadow-root">shadow root</a> of the <a href="#dfn-shadow-tree">shadow tree</a>, <a href="#dfn-distribution">distributed</a> to this <a href="#dfn-shadow-insertion-point">shadow insertion point</a></li>
</ul>

<p>If the <dfn id="dfn-reset-style-inheritance">reset-style-inheritance</dfn> flag is set for a <a href="#dfn-shadow-tree">shadow tree</a>, all <a target='_blank' href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#inheritance">inheritable</a> CSS properties <strong>must</strong> behave as if they were explicitly set to the <a target='_blank' href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#initial0">initial value</a> at the upper boundary of the tree.</p>

<p>If the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag is set for an <a href="#dfn-insertion-point">insertion point</a> in a <a href="#dfn-shadow-tree">shadow tree</a>, all <a target='_blank' href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#inheritance">inheritable</a> CSS properties <strong>must</strong> behave as if they were explicitly set to the <a target='_blank' href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#initial0">initial value</a> at the lower boundary of the tree.</p>

<h3 id="css-variables">CSS Variables</h3>

<p>The <a href="#dfn-shadow-host">shadow host</a> styles being inherited by the children of the <a href="#dfn-shadow-root">shadow root</a> <strong>must</strong> also apply to <a target='_blank' href="http://dev.w3.org/csswg/css-variables/">CSS Variables</a>. This provides a way for <a href="#dfn-document-tree">document tree</a> styles to send signals into the <a href="#dfn-shadow-tree">shadow trees</a>, and for the <a href="#dfn-shadow-tree">shadow trees</a> to receive these signals with the use of the <a target='_blank' href="http://dev.w3.org/csswg/css-variables/#using-variables"><code>var()</code></a> function.</p>

<h3 id="text-decoration-property"><code>text-decoration</code> Property</h3>

<p>The text decorations, specified by the <a target='_blank' href="http://www.w3.org/TR/CSS2/text.html#lining-striking-props"><code>text-decoration</code></a> property <strong>must not</strong> be propagated from <a href="#dfn-shadow-host">shadow hosts</a> to <a href="#dfn-shadow-tree">shadow trees</a>.</p>

<h3 id="host-at-rule"><code>@host</code> @-rule</h3>

<p>Within styles, specified in <a href="#dfn-shadow-tree">shadow trees</a>, the author may use a <code>@host</code> @-rule. The syntax of this rule is defined as this addition to <a target='_blank' href="http://www.w3.org/TR/CSS21/grammar.html">CSS Grammar</a>:</p>

<p>The following production is added to the <a target='_blank' href="http://www.w3.org/TR/CSS21/grammar.html#grammar">grammar</a>:</p>

<pre><code>
host
    : HOST_SYM S* '{' S* ruleset* '}' S*
    ;
</code></pre>

<p>The following rule is added to the <a target='_blank' href="http://www.w3.org/TR/CSS21/grammar.html#scanner">tokenizer</a>:</p>

<pre><code>
@{H}{O}{S}{T}        {return HOST_SYM;}
</code></pre>

<p>The <a target='_blank' href="http://www.w3.org/TR/CSS21/syndata.html#x19">declarations</a> of the rules in a <code>@host</code> @-rule <strong>must</strong> only be matched against the <a href="#dfn-shadow-host">shadow host</a> of the <a href="#dfn-shadow-tree">shadow tree</a> in which the style is specified, but only if this <a href="#dfn-shadow-tree">shadow tree</a> is <a href="#dfn-rendering">rendered</a>. When the <a href="#dfn-shadow-tree">shadow tree</a> is not <a href="#dfn-rendering">rendered</a> (when it's an older <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> that is not assigned to a <a href="#dfn-shadow-insertion-point">shadow insertion point</a>), the <a target='_blank' href="http://www.w3.org/TR/CSS21/syndata.html#x19">declarations</a> <strong>must not</strong> be applied.</p>

<p>When a rule in <a href="#host-at-rule"><code>@host</code> @-rule</a> matches an <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a>, it <strong>must</strong> have higher <a target='_blank' href="http://www.w3.org/TR/CSS2/cascade.html#specificity">specificity</a> than any <a target='_blank' href="http://www.w3.org/TR/selectors/">selector</a>, but lower <a target='_blank' href="http://www.w3.org/TR/CSS2/cascade.html#specificity">specificity</a> than <a target='_blank' href="http://www.w3.org/TR/CSS21/syndata.html#x19">declarations</a> from a <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#the-style-attribute"><code>style</code></a> attribute.</p>


<section class="mechanics">

<h2 id="user-interaction">User Interaction</h2>

<h3 id="ranges-and-selection">Ranges and Selections</h3>

<p>Since a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> in a <a href="#dfn-document-tree">document tree</a> and a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">node</a> in a <a href="#dfn-shadow-tree">shadow tree</a> never have the same <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-tree-root">root</a>, there may never exist a valid <a target='_blank' href="http://www.w3.org/TR/domcore/#range">DOM range</a> that spans either both a <a href="#dfn-document-tree">document tree</a> and a <a href="#dfn-shadow-tree">shadow tree</a>, or multiple <a href="#dfn-shadow-tree">shadow trees</a>.</p>

<p>Accordingly, <a target='_blank' href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#concept-selection">selections</a> may only exist within one tree, because they are defined by a single <a target='_blank' href="http://www.w3.org/TR/domcore/#range">range</a>. To maintain <a href="#dfn-upper-boundary-encapsulation">upper boundary encapsulation</a>, the selection, returned by the <a target='_blank' href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#dom-window-getselection"><code>window.getSelection()</code></a> method <strong>must</strong> never return a selection within a <a href="#dfn-shadow-tree">shadow tree</a>.</p>

<p>The <code>getSelection()</code> method of the <a href="#dfn-shadow-root">shadow root</a> object <strong>must</strong> return the current <a target='_blank' href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#concept-selection">selection</a> in this <a href="#dfn-shadow-tree">shadow tree</a>.</p>

<h3 id="focus-navigation">Focus Navigation</h3>

<p><a href="#dfn-shadow-tree">shadow trees</a> participate in <a target='_blank' href="http://www.w3.org/TR/css3-ui/#keyboard">sequential</a> or <a target='_blank' href="http://www.w3.org/TR/css3-ui/#keyboard">directional</a> focus navigation as part of the <a href="#dfn-document-tree">document tree</a>. The <a target='_blank' href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a> within a <a href="#dfn-shadow-tree">shadow tree</a> <strong>must</strong> be computed as a list of <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#focusable">focusable</a> <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a> in <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#tree-order">tree order</a> <a href="#dfn-as-rendered">as-rendered</a>, with the exception of any <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a>, <a href="#dfn-distribution">distributed</a> into <a href="#dfn-insertion-point">insertion points</a>, and is called <dfn id="dfn-shadow-dom-navigation-order">shadow DOM navigation order</dfn>.</p>

<div class="informative">
Since the elements, distributed into insertion points are not part of the shadow tree, their order remains to be controlled by the navigation order of the nesting tree.
</div>

<p>For <a target='_blank' href="http://www.w3.org/TR/css3-ui/#keyboard">sequential focus navigation</a>, the <a href="#dfn-shadow-dom-navigation-order">shadow DOM navigation order</a> sequence <strong>must</strong> be inserted into the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a> <a target='_blank' href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a>:</p>
<ol>
    <li>immediately after the <a href="#dfn-shadow-host">shadow host</a>, if the shadow host is <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#focusable">focusable</a>; or</li>
    <li>in place of the <a href="#dfn-shadow-host">shadow host</a> as if the shadow host were assigned the value of <a target='_blank' href="http://www.w3.org/TR/css3-ui/#keyboard"><code>auto</code></a> for determining its position.</li>
</ol>

<p>For <a target='_blank' href="http://www.w3.org/TR/css3-ui/#keyboard">directional focus navigation</a>, it is up to the user agent to integrate the <a href="#dfn-shadow-dom-navigation-order">shadow DOM navigation order</a> into the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a> <a target='_blank' href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a>.</p>

<h3 id="active-element">Active Element</h3>

<p>To maintain <a href="#dfn-upper-boundary-encapsulation">upper-boundary encapsulation</a>, the value of the <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#document">Document</a> object's focus API property <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#dom-document-activeelement">activeElement</a> <strong>must</strong> be adjusted. To prevent loss of information when adjusting this value, each <a href="#dfn-shadow-root">shadow root</a> <strong>must</strong> also have an <code>activeElement</code> property to store the value of the focused <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> in the <a href="#dfn-shadow-tree">shadow tree</a>.</p>

<p>The <dfn id="active-element-adjustment-algorithm">active <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> adjustment algorithm</dfn> is used to determine the values of the respective <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#dom-document-activeelement">activeElement</a> properties, and it <strong>must</strong> be equivalent to processing the following steps:</p>

<div class="algorithm">
<dl>
<dt>Input</dt>
    <dd><var>ELEMENT</var>, the focused <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a></dd>
<dt>Output</dt>
    <dd>Adjusted values of <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#dom-document-activeelement">activeElement</a> properties.</dd>
</dl>
<ol>
    <li>Run the <a href="#dfn-retargeting-algorithm">retargeting algorithm</a> with <var>ELEMENT</var> as input</li>
    <li>For each <var>TUPLE</var> in the resulting list of tuples:
    <ol>
        <li>Let <var>ADJUSTED</var> be the first value of the <var>TUPLE</var></li>
        <li>Let <var>NODE</var> be the second value of the <var>TUPLE</var></li>
        <li>If <var>NODE</var> is a <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#document">Document</a> or a <a href="#dfn-shadow-root">shadow root</a>, set the value of the <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#dom-document-activeelement">activeElement</a> to <var>ADJUSTED</var>.</li>
    </ol>
    </li>
</ol>
</div>

<h3 id="editing">Editing</h3>

<p>The value of the <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#attr-contenteditable"><code>contenteditable</code></a> attribute <strong>must not</strong> propagate from <a href="#dfn-shadow-host">shadow host</a> to its <a href="#dfn-shadow-tree">shadow trees</a>.</p>

<h3 id="assistive-technology">Assistive Technology</h3>

<p>User agents with assistive technology traverse the <a href="#dfn-document-tree">document tree</a> <a href="#dfn-as-rendered">as rendered</a>, and thus enable full use of of <a target='_blank' href="http://www.w3.org/WAI/PF/aria/">WAI-ARIA</a> semantics in the <a href="#dfn-shadow-tree">shadow trees</a>.</p>

<h2 id="html-elements">HTML Elements in Shadow Trees</h2>

<p>Comparatively, a <a href="#dfn-shadow-tree">shadow tree</a> can be seen as somewhere between <em>just part of a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a></em> and itself being a <a target='_blank' href="http://www.w3.org/TR/domcore/#interface-documentfragment">document fragment</a>. Since it is rendered, a <a href="#dfn-shadow-tree">shadow tree</a> aims to retain the traits of a typical <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> in a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a>. At the same time, it is an encapsulation abstraction, so it has to avoid affecting the <a href="#dfn-document-tree">document tree</a>. Thus, the <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> <strong>must</strong> behave <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">as specified</a> in the <a href="#dfn-shadow-tree">shadow trees</a>, with a few exceptions.</p>

<h3 id="inert-html-elements">Inert HTML Elements</h3>

<p>A subset of <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> <strong>must</strong> behave as <dfn id="dfn-inert">inert</dfn>, or not part of the <a href="#dfn-document-tree">document tree</a>. This is consistent how the <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> would behave in a <a target='_blank' href="http://www.w3.org/TR/domcore/#interface-documentfragment">document fragment</a>. These <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a> are:</p>
<ul>
    <li><a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-base-element"><code>base</code></a></li>
    <li><a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-link-element"><code>link</code></a></li>
</ul>

<p>All other <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> in the <a href="#dfn-shadow-tree">shadow trees</a> <strong>must</strong> behave as if they were part of the <a href="#dfn-document-tree">document tree</a>, with the <a href="#dfn-scoping-constraints">scoping constraints</a> of their respective trees applied.</p>

<h3 id="html-forms">HTML Forms</h3>

<p>The <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#forms">forms</a> in HTML are scoped at the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a> level. That is, all <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#the-form-element"><code>form</code></a> <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a> and <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#form-associated-element">form-associated elements</a> are accessible using the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a> <a target='_blank' href="http://www.w3.org/TR/domcore/#interface-document">DOM object</a>'s <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-tree-accessors">tree accessors</a>. Per <a href="#dfn-scoping-constraints">scoping constraints</a>, this <strong>must</strong> exclude <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a> in the <a href="#dfn-shadow-tree">shadow trees</a>.</p>

<p>Instead, each <a href="#dfn-shadow-tree">shadow tree</a> <strong>must</strong> scope its <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#the-form-element"><code>form</code></a> <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a> and <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#form-associated-element">form-associated elements</a>. Because the <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#the-form-element"><code>form</code></a>'s <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-node-ownerdocument"><code>ownerDocument</code></a> is the <a href="#dfn-shadow-host">shadow host</a>'s <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a>, the form submission <strong>must</strong> continue to work <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#form-submission">as specified</a>.</p>

<h2 id="html-elements-and-their-shadow-trees">HTML Elements and Their Shadow Trees</h2>

<p>Per <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/">specification</a>, some <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> are designed to either not render their contents or have special requirements in regard to contents rendering. In order to reconcile these differences in rendering behavior with the <a href="#dfn-shadow-dom">shadow DOM</a> <a href="#dfn-tree-composition">tree composition</a>, all <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> <strong>must</strong> have an <a href="#dfn-processing-equivalence">equivalent</a> of a <a href="#dfn-shadow-tree">shadow tree</a> that is created and populated at the time of <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> instantiation. It is up to a user agent to define the content of these trees. However, all conforming user agents <strong>must</strong> satisfy the following requirements:</p>

<table>
<thead>
    <tr>
        <th style="width: 30%">HTML Element</th>
        <th>Shadow Tree Requirements</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td><a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/embedded-content-1.html#the-img-element"><code>img</code></a>, <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-iframe-element.html#the-iframe-element"><code>iframe</code></a>, <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-iframe-element.html#the-embed-element"><code>embed</code></a>, <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-iframe-element.html#the-object-element"><code>object</code></a>, <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-video-element.html#the-video-element"><code>video</code></a>, <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-video-element.html#the-audio-element"><code>audio</code></a>, <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#the-canvas-element"><code>canvas</code></a>, <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-map-element.html#the-map-element"><code>map</code></a>, <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-input-element.html#the-input-element"><code>input</code></a>, <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-button-element.html#the-textarea-element"><code>textarea</code></a>, <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-button-element.html#the-progress-element"><code>progress</code></a>, <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-button-element.html#the-meter-element"><code>meter</code></a></td>
        <td>If the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> can have <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#fallback-content">fallback content</a>, contains one <a href="#dfn-insertion-point">insertion point</a>. The <a href="#dfn-matching-criteria">matching criteria</a> value is the <a target='_blank' href="http://www.w3.org/TR/css3-selectors/#universal-selector">universal selector</a> only when the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> needs to show <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#fallback-content">fallback content</a>. Otherwise, contains no <a href="#dfn-insertion-point">insertion points</a> or an <a href="#dfn-insertion-point">insertion point</a> that matches nothing.</td>
    </tr>
    <tr>
        <td><a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#the-fieldset-element"><code>fieldset</code></a></td>
        <td>Contains two <a href="#dfn-insertion-point">insertion points</a> with the following <a href="#dfn-matching-criteria">matching criteria</a>:
        <ol>
            <li><code>legend:first-of-type</code></li>
            <li><a target='_blank' href="http://www.w3.org/TR/css3-selectors/#universal-selector">universal selector</a></li>
        </ol>
        </td>
    </tr>
    <tr>
        <td><a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/interactive-elements.html#the-details-element"><code>details</code></a></td>
        <td>Contains two <a href="#dfn-insertion-point">insertion points</a> with the following <a href="#dfn-matching-criteria">matching criteria</a>:
        <ol>
            <li><code>summary:first-of-type</code></li>
            <li><a target='_blank' href="http://www.w3.org/TR/css3-selectors/#universal-selector">universal selector</a></li>
        </ol>
        </td>
    </tr>
    <tr>
        <td>All other <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">elements</a></td>
        <td>Contains one <a href="#dfn-insertion-point">insertion point</a> with the <a target='_blank' href="http://www.w3.org/TR/css3-selectors/#universal-selector">universal selector</a> as the <a href="#dfn-matching-criteria">matching criteria</a></td>
    </tr>
</tbody>
</table>

<h2 id="elements-and-dom-objects">Elements and DOM Objects</h2>

<h3 id="shadow-root-object"><code>ShadowRoot</code> Object</h3>

<p>The <code>ShadowRoot</code> object represents the <a href="#dfn-shadow-root">shadow root</a>.</p>
    
<pre><code>
interface <dfn id="api-shadow-root">ShadowRoot</dfn> : <a target='_blank' href="http://www.w3.org/TR/domcore/#interface-documentfragment">DocumentFragment</a> {
    <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#htmlelement">HTMLElement</a> <a href="#api-shadow-root-get-element-by-id">getElementById</a>(DOMString elementId);
    <a target='_blank' href="http://www.w3.org/TR/domcore/#nodelist">NodeList</a> <a href="#api-shadow-root-get-elements-by-class-name">getElementsByClassName</a>(DOMString tagName);
    <a target='_blank' href="http://www.w3.org/TR/domcore/#nodelist">NodeList</a> <a href="#api-shadow-root-get-elements-by-tag-name">getElementsByTagName</a>(DOMString className);
    <a target='_blank' href="http://www.w3.org/TR/domcore/#nodelist">NodeList</a> <a href="#api-shadow-root-get-elements-by-tag-name-ns">getElementsByTagNameNS</a>(DOMString? namespace, DOMString localName);
    <a target='_blank' href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#selection">Selection</a>? <a href="#api-shadow-root-selection">getSelection</a>();
    <a target='_blank' href="http://www.w3.org/TR/domcore/#interface-element">Element</a>? <a href="#api-shadow-root-element-from-point">elementFromPoint</a>(float x, float y);
    <a target='_blank' href="http://www.w3.org/TR/cssom/#the-cssstylesheet-interface">CSSStyleSheet</a> <a href="#api-shadow-root-add-style-sheet">addStyleSheet</a>(HTMLElement element);
    <a target='_blank' href="http://www.w3.org/TR/cssom/#the-cssstylesheet-interface">CSSStyleSheet</a> <a href="#api-shadow-root-remove-style-sheet">removeStyleSheet</a>(<a target='_blank' href="http://www.w3.org/TR/cssom/#the-cssstylesheet-interface">CSSStyleSheet</a> styleSheet);
    attribute bool <a href="#api-shadow-root-apply-author-styles">applyAuthorStyles</a>;
    attribute bool <a href="#api-shadow-root-reset-style-inheritance">resetStyleInheritance</a>;
    readonly attribute <a target='_blank' href="http://www.w3.org/TR/domcore/#interface-element">Element</a>? <a href="#api-shadow-root-active-element">activeElement</a>;
    attribute DOMString <a href="#api-shadow-root-inner-html">innerHTML</a>;
    readonly attribute <a target='_blank' href="http://www.w3.org/TR/cssom/#the-stylesheet-interface">StyleSheetList</a> <a href="#api-shadow-root-style-sheets">styleSheets</a>;
}
</code></pre>

<h4 id="shadow-root-attributes"><code>ShadowRoot</code> Attributes</h4>

<dl>
<dt id="api-shadow-root-apply-author-styles"><code>applyAuthorStyles</code> of type <code>bool</code></dt>
<dd>Represents the <a href="#dfn-apply-author-styles">apply-author-styles</a> flag and indicates whether or not the rules in <a target='_blank' href="http://www.w3.org/TR/CSS2/cascade.html">author styles</a> associated with the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a>'s <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-document">document</a> apply to the <a href="#dfn-shadow-tree">shadow tree</a>. If <code>false</code> (default value), the author styles <strong>are not</strong> applied to the <a href="#dfn-shadow-tree">shadow tree</a>. If <code>true</code>, the author styles <strong>are</strong> applied.</dd>
<dd>On getting, the attribute <strong>must</strong> return the current value of the <a href="#dfn-apply-author-styles">apply-author-styles</a> flag for the <a href="#dfn-shadow-host">shadow host</a>'s tree.</dd>
<dd>On setting, the attribute <strong>must</strong> set the value of the <a href="#dfn-apply-author-styles">apply-author-styles</a> flag for the <a href="#dfn-shadow-host">shadow host</a>'s <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> to specified value.</dd>
<dt id="api-shadow-root-reset-style-inheritance"><code>resetStyleInheritance</code> of type <code>bool</code></dt>
<dd>Represents the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag and indicates whether or not the inheritable CSS properties are set to the initial value at the shadow boundary. If <code>false</code> (default value), the properties continue to inherit. If <code>true</code>, the properties are set to initial value.</dd>
<dd>On getting, the attribute <strong>must</strong> return the current value of the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag for the <a href="#dfn-shadow-host">shadow host</a>'s tree.</dd>
<dd>On setting, the attribute <strong>must</strong> set the value of the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag for the <a href="#dfn-shadow-host">shadow host</a>'s <a target='_blank' href="http://www.w3.org/TR/domcore/#trees">tree</a> to specified value.</dd>
<dt id="api-shadow-root-active-element"><code>activeElement</code> of type <code>Element</code>, readonly</dt>
<dd>Represents the currently focused <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> in the <a href="#dfn-shadow-tree">shadow tree</a>.</dd>
<dd>On getting, the attribute <strong>must</strong> return the currently focused <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> in the <a href="#dfn-shadow-tree">shadow tree</a> or <code>null</code>, if there is none.</dd>
<dt id="api-shadow-root-inner-html"><code>innerHTML</code> of type <code>DOMString</code></dt>
<dd>represents the markup of <a href="#api-shadow-root"><code>ShadowRoot</code></a>'s contents.</dd>
<dd>On getting, the attribute <strong>must</strong> return the result of running the <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-end.html#html-fragment-serialization-algorithm">HTML fragment serialization algorithm</a> with the <a target='_blank' href="http://html5.org/specs/dom-parsing.html#context-object">context object</a> as <a href="#dfn-shadow-host"><code>shadow host</code></a>.</dd>
<dd>On setting, these steps <strong>must</strong> be run:
<ol>
    <li>Let <var>FRAGMENT</var> be the result of invoking the <a target='_blank' href="http://html5.org/specs/dom-parsing.html#concept-parse-fragment">fragment parsing algorithm</a> with the new value as <var>MARKUP</var>, and the <a target='_blank' href="http://html5.org/specs/dom-parsing.html#context-object">context object</a> as <a href="#dfn-shadow-host"><code>shadow host</code></li>
    <li><a target='_blank' href="http://www.w3.org/TR/dom/#concept-node-replace-all">Replace all</a> with <var>FRAGMENT</var> within the <a href="#dfn-shadow-root">shadow root</a>.</li>
</ol></dd>
<dt id="api-shadow-root-style-sheets"><code>styleSheets</code> of type <code>StyleSheetList</code>, readonly</dt>
<dd>Represents the <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>.</dd>
<dd>On getting, the attribute <strong>must</strong> return a <code>StyleSheetList</code> sequence containing the <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>.
</dd>
</dl>

<p>The <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-node-nodetype"><code>nodeType</code></a> attribute of a <a href="#api-shadow-root"><code>ShadowRoot</code></a> instance <strong>must</strong> return <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-node-document_fragment_node"><code>DOCUMENT_FRAGMENT_NODE</code></a>. Accordingly, the <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-node-nodename"><code>nodeName</code></a> attribute of a <a href="#api-shadow-root"><code>ShadowRoot</code></a> instance <strong>must</strong> return <code>"#document-fragment"</code>.</p>

<h4 id="shadow-root-methods"><code>ShadowRoot</code> Methods</h4>

<dl>
<dt id="api-shadow-root-get-element-by-id"><code>getElementById</code></dt>
<dd><strong>Must</strong> behave exactly like <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-document-getelementbyid">document.getElementById</a>, except <a href="#dfn-scoping-constraints">scoped</a> to the <a href="#dfn-shadow-tree">shadow tree</a>.</dd>
<dt id="api-shadow-root-get-elements-by-class-name"><code>getElementsByClassName</code></dt>
<dd><strong>Must</strong> behave exactly like <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-document-getelementsbyclassname">document.getElementsByClassName</a>, except <a href="#dfn-scoping-constraints">scoped</a> to the <a href="#dfn-shadow-tree">shadow tree</a>.</dd>
<dt id="api-shadow-root-get-elements-by-tag-name"><code>getElementsByTagName</code></dt>
<dd><strong>Must</strong> behave exactly like <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-document-getelementsbytagname">document.getElementsByTagName</a>, except <a href="#dfn-scoping-constraints">scoped</a> to the <a href="#dfn-shadow-tree">shadow tree</a>.</dd>
<dt id="api-shadow-root-get-elements-by-tag-name-ns"><code>getElementsByTagNameNS</code></dt>
<dd><strong>Must</strong> behave exactly like <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-document-getelementsbytagnamens">document.getElementsByTagNameNS</a>, except <a href="#dfn-scoping-constraints">scoped</a> to the <a href="#dfn-shadow-tree">shadow tree</a>.</dd>
<dt id="api-shadow-root-selection"><code>getSelection</code><dt>
<dd>Returns the current selection in the <a href="#dfn-shadow-tree">shadow tree</a>.</dd>
<dd>When invoked, it <strong>must</strong> return the <a target='_blank' href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#concept-selection">selection</a> in the <a href="#dfn-shadow-host">shadow host</a>'s tree.</dd>

<dt id="api-shadow-root-element-from-point"><code>elementFromPoint</code></dt>
<dd>Returns an <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> at specified coordinates.
<div class="informative">Eventually, this needs to be part of <a target='_blank' href="http://dvcs.w3.org/hg/csswg/raw-file/tip/cssom-view/Overview.html">CSSOM View Module</a> specification</div>
When invoked, it <strong>must</strong> return result of running the following steps:
<ol>
    <li>If <a target='_blank' href="http://html5.org/specs/dom-parsing.html#context-object">context object</a> is not a <a href="#api-shadow-root"><code>ShadowRoot</code></a> instance, throw a <a target='_blank' href="http://www.w3.org/TR/domcore/#typemismatcherror"><code>TypeMismatchError</code></a>.</li>
    <li>If either argument is negative, <code>x</code> is greated than the <a target='_blank' href="http://dvcs.w3.org/hg/csswg/raw-file/tip/cssom-view/Overview.html#viewport">viewport</a> width excluding the size of a rendered scroll bar (if any), or if <code>y</code> is greated than the <a target='_blank' href="http://dvcs.w3.org/hg/csswg/raw-file/tip/cssom-view/Overview.html#viewport">viewport</a> height excluding the size of a rendered scroll bar (if any), return <strong>null</strong>.</li>
    <li>Let <var>HIT</var> be the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> at coordinates <code>x</code> and <code>y</code> in the <a target='_blank' href="http://dvcs.w3.org/hg/csswg/raw-file/tip/cssom-view/Overview.html#viewport">viewport</a>, determined through hit testing</li>
    <li>Let <var>TARGETS</var> be the result of running the <a href="#dfn-retargeting-algorithm">retargeting algorithm</a> with <var>HIT</var> as its argument</li>
    <li>Let <var>TUPLE</var> be the tuple in <var>TARGETS</var>, whose <em>second</em> value is <a target='_blank' href="http://html5.org/specs/dom-parsing.html#context-object">context object</a></li>
    <li>Return <em>first</em> value of <var>TUPLE</var>.</li>
</ol></dd>

<dt id="api-shadow-root-add-style-sheet"><code>addStyleSheet</code></dt>
<dd>Adds a new <a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a> to <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>.
<div class="informative">
There is a <a target='_blank' href="http://lists.w3.org/Archives/Public/www-style/2012Oct/thread.html#msg491">discussion</a> under way in the <a target='_blank' href="http://www.w3.org/Style/CSS/">CSS WG</a> to make <a target='_blank' href="http://www.w3.org/TR/cssom/#the-cssstylesheet-interface">CSSStyleSheet</a> constructable. Once that is the case, this API will change to simply accept a <a target='_blank' href="http://www.w3.org/TR/cssom/#the-cssstylesheet-interface">CSSStyleSheet</a> object.
</div>
</dd>
<dd>When invoked, the method <strong>must</strong> run the following steps:
<ol>
    <li>If the parameter is an <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#htmllinkelement">HTMLLinkElement</a>:
    <ol>
        <li>Follow <a target='_blank' href="http://www.w3.org/TR/cssom/#requirements-on-user-agents-implementing-the-http-link-header">requirements</a> for implementing the HTTP <code>link</code> header with the exception that the newly created style sheet <strong>must</strong> be appended to the <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>, not <a target='_blank' href="http://www.w3.org/TR/cssom/#document-style-sheets">document style sheets</a></li>
        <li>Return the newly created <a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a> object.</li>
    </ol></li>
    <li>If the parameter is an <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#htmlstyleelement">HTMLStyleElement</a>:
    <ol>
        <li><a target='_blank' href="http://www.w3.org/TR/cssom/#create-a-style-sheet">Create a style sheet</a> with the following properties and the exception that the newly created style sheet <strong>must</strong> be appended to the <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>, not <a target='_blank' href="http://www.w3.org/TR/cssom/#document-style-sheets">document style sheets</a>:
        <dl>
            <dt><a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet-location">style sheet location</a></dt>
            <dd>null</dd>
            <dt><a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet-owner-node">style sheet owner node</a></dt>
            <dd>null</dd>
            <dt><a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet-parent">style sheet parent</a></dt>
            <dd>null</dd>
            <dt><a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet-owner-css-rule">style sheet owner CSS rule</a></dt>
            <dd>null</dd>
            <dt><a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet-owner-css-rule">style sheet owner CSS rule</a></dt>
            <dd>null</dd>
            <dt><a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet-media">style sheet media</a></dt>
            <dd>null</dd>
            <dt><a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet-title">style sheet title</a></dt>
            <dd>null</dd>
            <dt><a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet-alternate-flag">style sheet alternate flag</a></dt>
            <dd>false</dd>
        </dl></li>
        <li>Return the newly created <a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a> object.</li>
    </ol>
    <li>Otherwise, throw a <a target='_blank' href="http://www.w3.org/TR/domcore/#typemismatcherror"><code>TypeMismatchError</code></a> exception.</li>
</ol></dd>
<dt id="api-shadow-root-remove-style-sheet"><code>removeStyleSheet</code></dt>
<dd>Removes a <a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a>, added with <a href="#api-shadow-root-add-style-sheet"><code>addStyleSheet</code></a>.</dd>
<dd>When invoked, the method <strong>must</strong> run these steps:
<ol>
    <li>If the <a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a>, represented by the method parameter exists in the <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a> and was added with <a href="#api-shadow-root-add-style-sheet"><code>addStyleSheet</code></a>:
    <ol>
        <li>Remove the <a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a> from <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>.</li>
        <li>Return the removed <a target='_blank' href="http://www.w3.org/TR/cssom/#style-sheet">style sheet</a> instance.</li>
    </ol></li>
    <li>Otherwise, throw a <a target='_blank' href="http://www.w3.org/TR/domcore/#nomodificationallowederror"><code>NoModificationAllowedError</code></a> exception.</li>
</ol></dd>
</dl>

<p>Invoking the <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-node-clonenode"><code>cloneNode()</code></a> method on a <a href="#api-shadow-root"><code>ShadowRoot</code></a> instance <strong>must</strong> always throw a <a target='_blank' href="http://www.w3.org/TR/domcore/#dom-domexception-data_clone_err"><code>DATA_CLONE_ERR</code></a> exception.</p>


<h3 id="extensions-to-element">Extensions to <code>Element</code> Interface</h3>

<pre><code>
interface <dfn id="api-shadow-aware">ShadowAware</dfn> {
    <a href="#api-shadow-root">ShadowRoot</a> <a href="#api-shadow-aware-create-shadow-root">createShadowRoot</a>();
    readonly attribute <a href="#api-shadow-root">ShadowRoot</a>? <a href="#api-shadow-aware-shadow-root">shadowRoot</a>;
    attribute DOMString <a href="#api-shadow-aware-pseudo">pseudo</a>;
}
<a target='_blank' href="http://www.w3.org/TR/domcore/#interface-element">Element</a> implements <a href="#api-shadow-aware">ShadowAware</a>;
</code></pre>

<h4 id="shadow-aware-attributes"><code>ShadowAware</code> Attributes</h4>

<dl>
<dt><dfn id="api-shadow-aware-pseudo">pseudo</dfn> of type <code>DOMString</code></dt>
<dd>Represents the <a href="#dfn-custom-pseudo-element-value">custom pseudo-element value</a>, associated with the <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a>.</dd>
<dd>On getting, the attribute <strong>must</strong> return the current <a href="#dfn-custom-pseudo-element-value">custom pseudo-element value</a> or <strong>empty string</strong> if there is no <a href="#dfn-custom-pseudo-element">custom pseudo-element</a> associated with this <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a>.</dd>
<dd>On setting, these steps <strong>must</strong> be run:
<ol>
    <li>If the <a href="#dfn-custom-pseudo-element">custom pseudo-element</a>, associated with this <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> already exists, discard it</li>
    <li>If the new value is not <strong>null</strong>, create a new <a href="#dfn-custom-pseudo-element">custom pseudo-element</a> with <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a> and the new value as its <a href="#dfn-custom-pseudo-element-value">value</a>.</li>
</ol></dd>
<dt><dfn id="api-shadow-aware-shadow-root">shadowRoot</dfn> of type <a href="#api-shadow-root"><code>ShadowRoot</code></a><dt>
<dd>Represents the top <a href="#dfn-shadow-tree">shadow tree</a> in the "<a href="#dfn-as-rendered">as rendered</a>" structure.</dd>
<dd>On getting, the attribute <strong>must</strong> return the <a href="#dfn-youngest-tree">youngest tree</a> that has the <a target='_blank' href="http://www.w3.org/TR/domcore/#context-object">context object</a> as its <a href="#dfn-shadow-host">shadow host</a>, or <strong>null</strong> if no such <a href="#dfn-shadow-tree">shadow tree</a> is accesible.</dd>
<dd>For <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a>, the <a href="#html-elements-and-their-shadow-trees">UA-provided</a> <a href="#dfn-shadow-tree">shadow trees</a> <strong>must not</strong> be accessible.</dd>
</dl>

<h4 id="shadow-aware-methods"><code>ShadowAware</code> Methods</h4>

<dl>
<dt><dfn id="api-shadow-aware-create-shadow-root"><code>createShadowRoot</code></dfn></dt>
<dd>When invoked, these steps <strong>must</strong> be run:
<ol>
    <li>If the <a target='_blank' href="http://www.w3.org/TR/domcore/#context-object">context object</a> is not an <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-element">element</a>, throw <a target='_blank' href="http://www.w3.org/TR/domcore/#typemismatcherror">TypeMismatchError</a> exception.</li>
    <li>Otherwise:
    <ol>
        <li>Create a new instance of the <a href="#api-shadow-root"><code>ShadowRoot</code></a> object</li>
        <li>Establish the <a target='_blank' href="http://www.w3.org/TR/domcore/#context-object">context object</a> as the <a href="#dfn-shadow-host">shadow host</a> of the <a href="#api-shadow-root"><code>ShadowRoot</code></a> object</li>
        <li>Add the <a href="#api-shadow-root"><code>ShadowRoot</code></a> object at the top of the <a href="#dfn-tree-stack">tree stack</a> of its <a href="#dfn-shadow-host">host</a></li>
        <li>Return <a href="#api-shadow-root"><code>ShadowRoot</code></a> object.</li>
    </ol></li>
</ol></dd>
</dl>


<h3 id="css-host-rule-interface"><code>CSSHostRule</code> Interface</h3>

<p>The <code>CSSHostRule</code> represents the <a href="#host-at-rule"><code>@host</code></a> at-rule in a CSS style sheet.</p>

<pre><code>
interface <dfn id="api-css-host-rule">CSSHostRule</dfn> : <a target='_blank' href="http://dev.w3.org/csswg/cssom/#the-cssrule-interface">CSSRule</a> {
    readonly attribute <a target='_blank' href="http://dev.w3.org/csswg/cssom/#the-cssrulelist-sequence">CSSRuleList</a> <a href="#api-css-host-rule-css-rules">cssRules</a>;
    unsigned long <a href="#api-css-host-rule-insert-rule">insertRule</a>(DOMString rule, unsigned long index);
    void <a href="#api-css-host-rule-delete-rule">deleteRule</a>(unsigned long index);
};
</code></pre>

<h4 id="css-host-rule-attributes"><code>CSSHostRule</code> Attributes</h4>

<dl>
    <dt><dfn id="api-css-host-rule-css-rules"><code>cssRules</code></dfn> of type <a target='_blank' href="http://dev.w3.org/csswg/cssom/#the-cssrulelist-sequence">CSSRuleList</a></dt>
    <dd>Represents the CSS rules in the <code>@host</code> style block</dd>
    <dd>On getting, the attribute <strong>must</strong> return the list of all CSS rules, specified in the <code>@host</code> at-rule, represented by the <a target='_blank' href="http://domparsing.spec.whatwg.org/#context-object">context object</a>.</dd>
</dl>

<h4 id="css-host-rule-methods"><code>CSSHostRule</code> Methods</h4>

<dl>
    <dt><dfn id="api-css-host-rule-insert-rule"><code>insertRule(DOMSTring <em>rule</em>, unsigned long <em>index</em>)</code></dfn></dt>
    <dd>When invoked, the method <strong>must</strong> <a target='_blank' href="http://dvcs.w3.org/hg/csswg/raw-file/tip/cssom/Overview.html#insert-a-css-rule">insert a CSS rule</a> <em>rule</em> into the CSS rule list returned by <a href="#api-css-host-rule-css-rules"><code>cssRules</code></a> at <em>index</em>.</dd>
    <dt><dfn id="api-css-host-rule-delete-rule"><code>deleteRule(unsigned long <em>index</em>)</code></dfn></dt>
    <dd>When invoked, the method <strong>must</strong> <a target='_blank' href="http://dvcs.w3.org/hg/csswg/raw-file/tip/cssom/Overview.html#remove-a-css-rule">remove a CSS rule</a> <em>rule</em> from the CSS rule list returned by <a href="#api-css-host-rule-css-rules"><code>cssRules</code></a> at <em>index</em>.</dd>
</dl>

<p>The <code>HOST_RULE</code> type is added to <a target='_blank' href="http://dev.w3.org/csswg/cssom/#the-cssrule-interface">CSSRule</a> interface.</p>

<pre><code>
partial interface <a target='_blank' href="http://dev.w3.org/csswg/cssom/#the-cssrule-interface">CSSRule</a> {
    const unsigned short <a href="#api-css-rule-host-rule">HOST_RULE</a> = 1001;
};
</code></pre>

<dl>
    <dt><dfn id="api-css-rule-host-rule"><code>HOST_RULE</code></dfn></dt>
    <dd>When the value of the <code>type</code> attribute is <code>HOST_RULE</code>, then the object that implements this interface <strong>must</strong> implement <a href="#api-css-host-rule"><code>CSSHostRule</code></a> interface</a>.</dd>
</dl>

<h3 id="content-element">The <code>content</code> HTML element</h3>

<p>The <dfn id="dfn-content-element"><code>content</code></dfn> HTML element represents a <a href="#dfn-insertion-point">insertion point</a> in the <a href="#dfn-shadow-tree">shadow tree</a>.</p>

<dl>
<dt>Context</dt>
<dd>Where <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#flow-content-0">flow content</a> is expected.</dd>
<dt>Content model</dt>
<dd><a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#transparent">Transparent</a></dd>
<dt>Children</dt>
<dd>Anything as <a href="#dfn-fallback-content">fallback content</a></dd>
<dt>Content attributes</dt>
<dd><a target='_blank' href="http://dev.w3.org/html5/spec/Overview.html#global-attributes">Global attributes</a></dd>
<dd>
    <dl>
<!--    <dt id="markup-content-apply-shadow-styles"><code>apply-shadow-styles</code>, a <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attribute">boolean attribute</a></dt>
    <dd>indicates whether or not the rules in the scoped styles, defined in shadow tree are applied to the <a href="#dfn-shadow-host">shadow host</a>'s children that are inserted in place of this <code>content</code> element. If present, the styles are applied.</dd> -->
    <dt id="markup-content-select"><code>select</code>, a <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#comma-separated-tokens">set of comma-separated tokens</a></dt>
    <dd>
        defines the <a href="#dfn-matching-criteria">matching criteria</a> for <a href="#dfn-distribution">distributing</a> child <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> of the <a href="#dfn-shadow-host">shadow host</a>. Each token <strong>must</strong> be a valid <a href="#dfn-selector-fragment">selector fragment</a>. If any token is invalid, the entire value of the <code>select</code> attribute is considered invalid.
    </dd>
    <dt id="markup-content-reset-style-inheritance"><code>reset-style-inheritance</code>, a <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attribute">boolean</a> attribute</dt>
    <dd>indicates the state of the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag for this <a href="#dfn-insertion-point">insertion point</a>. If present, the value of the flag <strong>must</strong> be set to <strong>true</strong>. Otherwise, the value <strong>must</strong> be set to <strong>false</strong>.</dd>
    </dl>
</dd>
<dt>DOM Interface</dt>
<dd>
    <pre><code>
interface <dfn id="api-html-content-element">HTMLContentElement</dfn> : <a target='_blank' href="http://dev.w3.org/html5/spec/Overview.html#htmlelement">HTMLElement</a> {<!--    attribute bool <a href="#api-html-content-element-apply-shadow-styles">applyShadowStyles</a>; -->
    attribute DOMString <a href="#api-html-content-element-select">select</a>;
    attribute boolean <a href="#api-html-content-element-reset-style-inheritance">resetStyleInheritance</a>;
    <a target='_blank' href="http://www.w3.org/TR/domcore/#interface-nodelist">NodeList</a> <a href="#api-html-content-element-get-distributed-nodes">getDistributedNodes</a>();
}
    </code></pre>
    <dl>
    <dt>Attributes</dt>
    <dd>
    <dl>
<!--        <dt id="api-html-content-element-apply-shadow-styles"><code>applyShadowStyles</code> of type <code>bool</code></dt>
        <dd>Must <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#reflect">reflect</a> the <a href="#markup-content-apply-shadow-styles">apply-shadow-styles</a> attribute.</dd> -->
        <dt id="api-html-content-element-select"><code>select</code> of type <code>DOMString</code></dt>
        <dd><strong>Must</strong> <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#reflect">reflect</a> the <a href="#markup-content-select">select</a> attribute.</dd>
        <dt id="api-html-content-element-reset-style-inheritance"><code>resetStyleInheritance</code> of type <code>boolean</code></dt>
        <dd><strong>Must</strong> <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#reflect">reflect</a> the <a href="#markup-content-reset-style-inheritance">reset-style-inheritance</a> attribute.</dd>
    </dl>
    </dd>
    </dl>
    <dl>
        <dt>Methods</dt>
        <dd><dl>
            <dt id="api-html-content-element-get-distributed-nodes"><code>getDistributedNodes</code></dt>
            <dd><strong>Must</strong> return a <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-collection-static">static</a> <a target='_blank' href="http://www.w3.org/TR/domcore/#nodelist"><code>NodeList</code></a> consisting of nodes, currently <a href="#dfn-distribution">distributed</a> into this <a href="#dfn-insertion-point">insertion point</a>.</dd>
        </dl></dd>
    </dl>
</dd>
</dl>


<h3 id="shadow-element">The <code>shadow</code> HTML element</h3>

<p>The <dfn id="dfn-shadow-element"><code>shadow</code></dfn> HTML element represents an <a href="#dfn-shadow-insertion-point">shadow insertion point</a> in a <a href="#dfn-shadow-tree">shadow tree</a>.</p>

<dl>
<dt>Context</dt>
<dd>Where <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#flow-content-0">flow content</a> is expected.</dd>
<dt>Content model</dt>
<dd><a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#transparent">Transparent</a></dd>
<dt>Children</dt>
<dd>Anything as <a href="#dfn-fallback-content">fallback content</a></dd>
<dt>Content attributes</dt>
<dd><a target='_blank' href="http://dev.w3.org/html5/spec/Overview.html#global-attributes">Global attributes</a></dd>
<dd>
<dl>
    <dt id="markup-shadow-reset-style-inheritance"><code>reset-style-inheritance</code>, a <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attribute">boolean</a> attribute</dt>
    <dd>indicates the state of the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag for this <a href="#dfn-shadow-insertion-point">shadow insertion point</a>. If present, the value of the flag <strong>must</strong> be set to <strong>true</strong>. Otherwise, the value <strong>must</strong> be set to <strong>false</strong>.</dd>
</dl></dd>
<dt>DOM Interface</dt>
<dd>
    <pre><code>
interface <dfn id="api-html-shadow-element">HTMLShadowElement</dfn> : <a target='_blank' href="http://dev.w3.org/html5/spec/Overview.html#htmlelement">HTMLElement</a> {
    readonly attribute <a href="#api-shadow-root">ShadowRoot</a>? <a href="#api-html-shadow-element-older-shadow-root">olderShadowRoot</a>;
    attribute boolean <a href="#api-html-shadow-element-reset-style-inheritance">resetStyleInheritance</a>;
}
    </code></pre>
    <dl>
        <dt>Attributes</dt>
        <dd><dl>
            <dt id="api-html-shadow-element-older-shadow-root"><code>olderShadowRoot</code> of type <a href="#api-shadow-root"><code>ShadowRoot</code></a></dt>
            <dd>Represents the <a href="#dfn-shadow-tree">shadow tree</a> that is <a href="#dfn-as-rendered">rendered</a> in place of this <a href="#dfn-shadow-insertion-point">shadow insertion point</a></dd>
            <dd>On getting, the attribute <strong>must</strong> return a result that is <a href="#dfn-processing-equivalence">equivalent</a> to running the following steps:
            <ol>
                <li>Let <var>TREE</var> be the <a href="#dfn-shadow-tree">shadow tree</a> that contains the <a target='_blank' href="http://www.w3.org/TR/domcore/#context-object">context object</a></li>
                <li>If <var>TREE</var> does not exist, return <strong>null</strong>.</li>
                <li>If <a target='_blank' href="http://www.w3.org/TR/domcore/#context-object">context object</a>, in <a target='_blank' href="http://www.w3.org/TR/domcore/#concept-tree-order">tree order</a>, is not the first <a href="#dfn-active-insertion-point">active</a> instance of <a href="#dfn-shadow-element"><code>shadow</code></a> element in <var>TREE</var>, return <strong>null</strong>.</li>
                <li>Let <var>HOST</var> be the <a href="#dfn-shadow-host">shadow host</a> of <var>TREE</var></li>
                <li>From <var>HOST</var>'s <a href="#dfn-tree-stack">tree stack</a>, return the <a href="#dfn-older-tree">older tree</a> relative to <var>TREE</var>, or <strong>null</strong> if no such <a href="#dfn-shadow-tree">shadow tree</a> is accessible.</li>
            </ol></dd>
            <dd>For <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a>, the <a href="#html-elements-and-their-shadow-trees">UA-provided</a> <a href="#dfn-shadow-tree">shadow trees</a> <strong>must not</strong> be accessible.</dd>
            <dt id="api-html-shadow-element-reset-style-inheritance"><code>resetStyleInheritance</code> of type <code>boolean</code></dt>
            <dd><strong>Must</strong> <a target='_blank' href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#reflect">reflect</a> the <a href="#markup-shadow-reset-style-inheritance">reset-style-inheritance</a> attribute.</dd>
        </dl></dd>
    </dl>
</dd>
</dl>
</section>

<h2 id="shadow-dom-example">Shadow DOM Example</h2>

<p>Bob was asked to turn a simple list of links into a News Widget, which has links organized into two categories: breaking news and just news. The current document markup for the stories looks like this:</p>
<pre class="prettyprint"><code>
&lt;ul class=&quot;stories&quot;&gt;
    &lt;li&gt;&lt;a href=&quot;//example.com/stories/1&quot;&gt;A story&lt;/a&gt;&lt;/li&gt;
    &lt;li&gt;&lt;a href=&quot;//example.com/stories/2&quot;&gt;Another story&lt;/a&gt;&lt;/li&gt;
    &lt;li class=&quot;breaking&quot;&gt;&lt;a href=&quot;//example.com/stories/3&quot;&gt;Also a story&lt;/a&gt;&lt;/li&gt;
    &lt;li&gt;&lt;a href=&quot;//example.com/stories/4&quot;&gt;Yet another story&lt;/a&gt;&lt;/li&gt;
    &lt;li&gt;&lt;a href=&quot;//example.com/stories/4&quot;&gt;Awesome story&lt;/a&gt;&lt;/li&gt;
    &lt;li class=&quot;breaking&quot;&gt;&lt;a href=&quot;//example.com/stories/5&quot;&gt;Horrible story&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</code></pre>

<p>To organize the stories, Bob decides to use <strong>shadow DOM</strong>. Doing so will allow Bob to keep the document markup uncluttered, and harnessing the power of insertion point makes sorting stories by class name a very simple task. After getting another cup of <a target='_blank' href="http://en.wikipedia.org/wiki/List_of_coffee_beverages#Green_Eye">Green Eye</a>, he quickly mocks up the following shadow tree, to be hosted by the <code>ul</code> element:</p>
<pre class="prettyprint"><code>
&lt;div class=&quot;breaking&quot;&gt;
    &lt;ul&gt;
        &lt;content select=&quot;.breaking&quot;&gt;&lt;/content&gt; &lt;!-- insertion point for breaking news --&gt;
    &lt;/ul&gt;
&lt;/div&gt;
&lt;div class=&quot;other&quot;&gt;
    &lt;ul&gt;
        &lt;content&gt;&lt;/content&gt; &lt;!-- insertion point for the rest of the news --&gt;
    &lt;/ul&gt;
&lt;/div&gt;
</code></pre>
<p>Bob then styles the newborn widget according to comps from the designer by adding this to the shadow tree mockup:</p>
<pre class="prettyprint"><code>
&lt;style&gt;
    div.breaking {
        color: Red;
        font-size: 20px;
        border: 1px dashed Purple;
    }
    div.other {
        padding: 2px 0 0 0;
        border: 1px solid Cyan;
    }
&lt;/style&gt;
</code></pre>
<p>While pondering if his company should start looking for a new designer, Bob converts the mockup to code:</p>
<pre class="prettyprint"><code>
function createStoryGroup(className, contentSelector)
{
    var group = document.createElement('div');
    group.className = className;
    // Empty string in select attribute or absence thereof work the same, so no need for special handling.
    group.innerHTML = '&lt;ul&gt;&lt;content select=&quot;' + contentSelector + '&quot;&gt;&lt;/content&gt;&lt;/ul&gt;';
    return group;
}

function createStyle()
{
    var style = document.createElement('style');
    style.textContent = 'div.breaking { color: Red;font-size: 20px; border: 1px dashed Purple; }' +
        'div.other { padding: 2px 0 0 0; border: 1px solid Cyan; }';
    return style;
}

function makeShadowTree(storyList)
{
    var root = storyList.createShadowRoot();
    root.appendChild(createStyle());
    root.appendChild(createStoryGroup('breaking', '.breaking'));
    root.appendChild(createStoryGroup('other', ''));
}

document.addEventListener('DOMContentLoaded', function() {
    [].forEach.call(document.querySelectorAll('ul.stories'), makeShadowTree);
});
</code></pre>

<p>Well done, Bob! With the cup of coffee still half-full, the work is complete. Recognizing his awesomeness, Bob returns to teaching n00bs the ways of <a target='_blank' href="http://en.wikipedia.org/wiki/World_of_Warcraft">WoW</a>.</p>

<p>A few months pass.</p>

<p>It's election time. With Bob at his annual conference, Alice is charged with adding <strong>another</strong>, temporary box to the news widget, filled with election-related stories. Alice studies Bob's code, reads up on the shadow DOM spec and realizes that, thanks to multiple shadow tree support, she doesn't have to touch his code. As usual, her solution is elegant and simple, fitting neatly right under Bob's code:</p>
<pre class="prettyprint"><code>
// TODO(alice): BEGIN -- DELETE THIS CODE AFTER ELECTIONS ARE OVER.
var ELECTION_BOX_REMOVAL_DEADLINE = ...;

function createElectionStyle()
{
    var style = document.createElement('style');
    // TODO(alice): Check designer's desk for hallucinogens.
    style.textContent = 'div.election { color: Magenta;font-size: 24px; border: 2px dotted Fuchsia; }';
    return style;
}

function makeElectionShadowTree(storyList)
{
    var root = storyList.createShadowRoot();
    // Add and style election story box.
    root.appendChild(createElectionStyle());
    root.appendChild(createStoryGroup('election', '.election'));
    // Insert Bob's shadow tree under the election story box.
    root.appendChild(document.createElement('shadow'));
}

if (Date.now() &lt; ELECTION_BOX_REMOVAL_DEADLINE) {
    document.addEventListener('DOMContentLoaded', function() {
        [].forEach.call(document.querySelectorAll('ul.stories'), makeElectionShadowTree);
    });
}
// TODO(alice): END -- DELETE THIS CODE AFTER ELECTIONS ARE OVER.
</code></pre>
<p>Using the <code>shadow</code> element allows Alice to compose Bob's widget <strong>inside</strong> of hers&mdash;without having to change a line of production code. Smiling to herself, Alice realizes that Bob may have come up with a way to keep the document markup clean, but <strong>she</strong> is the one who takes the cake for using shadow tree composition in such a cool way.</p>

</section>


<h2 id="acknowledgements">Acknowledgements</h2>

<p><span class="vcard">David Hyatt</span> developed <a target='_blank' href="http://dev.w3.org/2006/xbl2/">XBL 1.0</a>, and <span class="vcard">Ian Hickson</span> co-wrote <a target='_blank' href="http://dev.w3.org/2006/xbl2/">XBL 2.0</a>. These documents provided tremendous insight into the problem of functional encapsulation and greatly influenced this specification.</p>

<p><span class="vcard">Alex Russell</span> and his considerable forethought triggered a new wave of enthusiasm around the subject of shadow DOM and how it can be applied practically on the Web.</p>

<p><span class="vcard">Dominic Cooney</span>, <span class="vcard">Hajime Morrita</span>, and <span class="vcard">Roland Steiner</span> worked tirelessly to scope the problem of functional encapsulation within the confines of the Web platform and provided a solid foundation for this document.</p>

<p>The editor would also like to thank <span class="vcard">Alex Komoroske</span>, <span class="vcard">Anne van Kesteren</span>, <span class="vcard">Brian Kardell</span>, <span class="vcard">Darin Fisher</span>, <span class="vcard">Eric Bidelman</span>, <span class="vcard">Deepak Sherveghar</span>, <span class="vcard">Edward O'Connor</span>, <span class="vcard">Elisée Maurer</span>, <span class="vcard">Elliott Sprehn</span>, <span class="vcard">Erik Arvidsson</span>, <span class="vcard">Glenn Adams</span>, <span class="vcard">Hayato Ito</span>, <span class="vcard">Jonas Sicking</span>, <span class="vcard">Malte Ubl</span>, <span class="vcard">Mike Taylor</span>, <span class="vcard">Oliver Nightingale</span>, <span class="vcard">Olli Pettay</span>, <span class="vcard">Rafael Weinstein</span>, <span class="vcard">Richard Bradshaw</span>, <span class="vcard">Ruud Steltenpool</span>, <span class="vcard">Sam Dutton</span>, <span class="vcard">Sergey G. Grekhov</span>, <span class="vcard">Shinya Kawanaka</span>, <span class="vcard">Tab Atkins</span>, and <span class="vcard">Takashi Sakamoto</span> for their comments and contributions to this specification.</p>

<p>This list is too short. There's a lot of work left to do. Please contribute by reviewing and filing bugs&mdash;and don't forget to ask the editor to add your name into this section.</p>

</body>
</html>
